@starci/hfs 4.11.22 → 4.12.2

package/runtime/scripts/hfs/secret-init.mjs

@@ -11,64 +11,60 @@ import { claimFile } from "../api/fs/claim-file.mjs";
 import { generateAppIdentity } from "./secret-bootstrap-crypto.mjs";
 import { materializeDeclaredPlaceholders } from "./sealed-members.mjs";
 import { defaultSops } from "./secret-sops.mjs";
-import {
-  mainCheckout,
-  outsideRepository,
-  privateDirectory,
-  secretRoots,
-} from "./secret-files.mjs";
-
-const PATH_RULE = String.raw`\.starcistacks[/\\][^/\\]+[/\\]secrets[/\\][^/\\]+\.enc(?:\.yaml)?$`;
+import { mainCheckout, outsideRepository, privateDirectory, secretRoots, } from "./secret-files.mjs";
+const PATH_RULE = String.raw `\.starcistacks[/\\][^/\\]+[/\\]secrets[/\\][^/\\]+\.enc(?:\.yaml)?$`;
 /** The rule an earlier init wrote, which matches legacy `.enc` members only; init and recipients treat it as the app's own. */
-const LEGACY_PATH_RULE = String.raw`\.starcistacks[/\\][^/\\]+[/\\]secrets[/\\][^/\\]+\.enc$`;
+const LEGACY_PATH_RULE = String.raw `\.starcistacks[/\\][^/\\]+[/\\]secrets[/\\][^/\\]+\.enc$`;
 /** The path_regex of one environment's rule: its members, current or legacy. */
-export const environmentRule = (environment) =>
-  String.raw`\.starcistacks[/\\]` + environment + String.raw`[/\\]secrets[/\\][^/\\]+\.enc(?:\.yaml)?$`;
+export const environmentRule = (environment) => String.raw `\.starcistacks[/\\]` + environment + String.raw `[/\\]secrets[/\\][^/\\]+\.enc(?:\.yaml)?$`;
 const AGE_IDENTITY_NAME = /^SOPS_AGE_KEY(?:_FILE)?$/i;
-
+const INITIALIZATION_PATH_RULES = [PATH_RULE, LEGACY_PATH_RULE];
 /** Bootstrap a new app with its own age identity; only its public recipient leaves this owner. */
-
-
 /** Bootstrap a new app with its own age identity; only the public recipient leaves this owner. */
-export function initializeAppIdentity(repoRoot, { write, tools } = {}) {
-  const privateDirectory = path.join(repoRoot, ".claude");
-  const privateFile = path.join(privateDirectory, "secret.env");
-  const directoryStat = fs.lstatSync(privateDirectory, { throwIfNoEntry: false });
-  if (directoryStat && (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()))
-    throw new Error("the app private identity directory must be an ordinary directory");
-  const privateStat = fs.lstatSync(privateFile, { throwIfNoEntry: false });
-  if (privateStat && (!privateStat.isFile() || privateStat.isSymbolicLink() || privateStat.nlink !== 1))
-    throw new Error("the app private identity must be an ordinary unlinked file");
-  let local;
-  try { local = privateStat ? (tools?.secretEnv ?? secretEnv)(privateDirectory, {}) : {}; }
-  catch { throw new Error("the app private environment could not be loaded safely"); }
-  if (Object.keys(local ?? {}).some((name) => AGE_IDENTITY_NAME.test(name)))
-    throw new Error("the app already has a private age identity; initialization must not rotate it");
-  const config = readInitializationConfig(path.join(repoRoot, ".sops.yaml"));
-  if ((config.creation_rules ?? []).some((rule) => rule?.age))
-    throw new Error("the app already has an age recipient; initialization must not rotate it");
-  const publish = write ?? ((file, content) => {
-    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-    const append = file === privateFile || file === path.join(privateDirectory, ".gitignore");
-    fs.writeFileSync(file, content, { mode: 0o600, flag: append ? "a" : "w" });
-  });
-  const generated = generateAppIdentity();
-  let privateContent;
-  try {
-    const prefix = privateStat ? "\nSOPS_AGE_KEY=" : "SOPS_AGE_KEY=";
-    privateContent = Buffer.concat([Buffer.from(prefix), generated.identity, Buffer.from("\n")]);
-    publish(path.join(privateDirectory, ".gitignore"), "\nsecret.env\n");
-    publish(privateFile, privateContent);
-    if (process.platform !== "win32") fs.chmodSync(privateFile, 0o600);
-    config.creation_rules = [{ path_regex: PATH_RULE, age: generated.recipient }];
-    publish(path.join(repoRoot, ".sops.yaml"), stringifyYaml(config));
-    return { recipient: generated.recipient, files: [".claude/.gitignore", ".claude/secret.env", ".sops.yaml"] };
-  } finally {
-    privateContent?.fill(0);
-    generated.identity.fill(0);
-  }
+export function initializeAppIdentity(repoRoot, { write, tools, } = {}) {
+    const privateDirectory = path.join(repoRoot, ".claude");
+    const privateFile = path.join(privateDirectory, "secret.env");
+    const directoryStat = fs.lstatSync(privateDirectory, { throwIfNoEntry: false });
+    if (directoryStat && (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()))
+        throw new Error("the app private identity directory must be an ordinary directory");
+    const privateStat = fs.lstatSync(privateFile, { throwIfNoEntry: false });
+    if (privateStat && (!privateStat.isFile() || privateStat.isSymbolicLink() || privateStat.nlink !== 1))
+        throw new Error("the app private identity must be an ordinary unlinked file");
+    let local;
+    try {
+        local = privateStat ? (tools?.secretEnv ?? secretEnv)(privateDirectory, {}) : {};
+    }
+    catch {
+        throw new Error("the app private environment could not be loaded safely");
+    }
+    if (Object.keys(local ?? {}).some((name) => AGE_IDENTITY_NAME.test(name)))
+        throw new Error("the app already has a private age identity; initialization must not rotate it");
+    const config = readInitializationConfig(path.join(repoRoot, ".sops.yaml"));
+    if ((config.creation_rules ?? []).some((rule) => rule?.age))
+        throw new Error("the app already has an age recipient; initialization must not rotate it");
+    const publish = write ?? ((file, content) => {
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        const append = file === privateFile || file === path.join(privateDirectory, ".gitignore");
+        fs.writeFileSync(file, content, { mode: 0o600, flag: append ? "a" : "w" });
+    });
+    const generated = generateAppIdentity();
+    let privateContent;
+    try {
+        const prefix = privateStat ? "\nSOPS_AGE_KEY=" : "SOPS_AGE_KEY=";
+        privateContent = Buffer.concat([Buffer.from(prefix), generated.identity, Buffer.from("\n")]);
+        publish(path.join(privateDirectory, ".gitignore"), "\nsecret.env\n");
+        publish(privateFile, privateContent);
+        if (process.platform !== "win32")
+            fs.chmodSync(privateFile, 0o600);
+        config.creation_rules = [{ path_regex: PATH_RULE, age: generated.recipient }];
+        publish(path.join(repoRoot, ".sops.yaml"), stringifyYaml(config));
+        return { recipient: generated.recipient, files: [".claude/.gitignore", ".claude/secret.env", ".sops.yaml"] };
+    }
+    finally {
+        privateContent?.fill(0);
+        generated.identity.fill(0);
+    }
 }
-
 /**
  * The app's host-local age selection: SOPS_AGE_KEY or SOPS_AGE_KEY_FILE of the explicit environment, else of the git-ignored
  * `.claude/secret.env` of the app root, else of its main checkout's when the root is a git worktree, else the SOPS_AGE_KEY the
@@ -77,338 +73,300 @@ export function initializeAppIdentity(repoRoot, { write, tools } = {}) {
  * null; `looked` lists every secret.env read, for a refusal that names them. No value ever leaves in `source` or `looked`.
  */
 export function localAgeIdentity(repoRoot, env, tools, host = null) {
-  const own = Object.keys(env).filter((name) => AGE_IDENTITY_NAME.test(name));
-  if (own.length) return { env: { ...env }, source: `the environment (${own.join(", ")})`, looked: [] };
-  const load = tools?.secretEnv ?? secretEnv;
-  const roots = [...new Set([repoRoot, mainCheckout(repoRoot)].map((root) => path.resolve(root)))];
-  const looked = [];
-  for (const root of roots) {
-    const file = path.join(root, ".claude", "secret.env");
-    looked.push(file);
-    let resolved;
-    try {
-      resolved = load(path.join(root, ".claude"), env) ?? {};
-    } catch {
-      continue;
+    const own = Object.keys(env).filter((name) => AGE_IDENTITY_NAME.test(name));
+    if (own.length)
+        return { env: { ...env }, source: `the environment (${own.join(", ")})`, looked: [] };
+    const load = tools?.secretEnv ?? secretEnv;
+    const roots = [...new Set([repoRoot, mainCheckout(repoRoot)].map((root) => path.resolve(root)))];
+    const looked = [];
+    for (const root of roots) {
+        const file = path.join(root, ".claude", "secret.env");
+        looked.push(file);
+        let resolved;
+        try {
+            resolved = load(path.join(root, ".claude"), env) ?? {};
+        }
+        catch {
+            continue;
+        }
+        const local = Object.fromEntries(Object.entries(resolved).filter(([name]) => AGE_IDENTITY_NAME.test(name)));
+        if (Object.keys(local).length)
+            return { env: { ...env, ...local }, source: `${file} (${Object.keys(local).join(", ")})`, looked };
     }
-    const local = Object.fromEntries(
-      Object.entries(resolved).filter(([name]) => AGE_IDENTITY_NAME.test(name)),
-    );
-    if (Object.keys(local).length)
-      return { env: { ...env, ...local }, source: `${file} (${Object.keys(local).join(", ")})`, looked };
-  }
-  if (host) {
-    looked.push(host.label);
-    const value = host.read();
-    if (typeof value === "string" && value.trim())
-      return { env: { ...env, SOPS_AGE_KEY: value.trim() }, source: `${host.label} (SOPS_AGE_KEY)`, looked };
-  }
-  return { env: { ...env }, source: null, looked };
+    if (host) {
+        looked.push(host.label);
+        const value = host.read();
+        if (typeof value === "string" && value.trim())
+            return { env: { ...env, SOPS_AGE_KEY: value.trim() }, source: `${host.label} (SOPS_AGE_KEY)`, looked };
+    }
+    return { env: { ...env }, source: null, looked };
 }
-
 /**
  * The one age identity every decrypt of a sealed member opens with (secret get, verify, materialize, set over an existing member,
  * migrate, split, the edit verbs, updatekeys, server-key, the stack's sealed members and the CLI's custody): localAgeIdentity's
  * order (the environment, the app's `.claude/secret.env`, its main checkout's, the `host` port), then sops' per-user keys.txt.
  * Same shape as localAgeIdentity; `looked` names every place read, keys.txt last.
  */
-export function decryptionIdentity(repoRoot, env, { tools, host = null, platform = process.platform } = {}) {
-  const local = localAgeIdentity(repoRoot, env, tools, host);
-  if (local.source !== null) return local;
-  const keys = secretRoots(env, platform).identity;
-  const looked = [...local.looked, keys];
-  if (!fs.existsSync(keys)) return { ...local, looked };
-  return { env: { ...local.env, SOPS_AGE_KEY_FILE: keys }, source: keys, looked };
+export function decryptionIdentity(repoRoot, env, { tools, host = null, platform = process.platform, } = {}) {
+    const local = localAgeIdentity(repoRoot, env, tools, host);
+    if (local.source !== null)
+        return local;
+    const keys = secretRoots(env, platform).identity;
+    const looked = [...local.looked, keys];
+    if (!fs.existsSync(keys))
+        return { ...local, looked };
+    return { env: { ...local.env, SOPS_AGE_KEY_FILE: keys }, source: keys, looked };
 }
-
 /** Load host-local age selections below the explicit environment (localAgeIdentity), without copying any other credentials. */
 export function ageIdentityEnv(repoRoot, env, tools) {
-  return localAgeIdentity(repoRoot, env, tools).env;
+    return localAgeIdentity(repoRoot, env, tools).env;
 }
-
 /** Select the first matching public age rule, including for SOPS's isolated CI identity path. */
 export function configuredRecipients(repoRoot, file) {
-  let config;
-  try {
-    config = parseYaml(
-      fs.readFileSync(path.join(repoRoot, ".sops.yaml"), "utf8"),
-    );
-  } catch {
-    throw new Error(
-      "a valid .sops.yaml is required; run starci app secret init",
-    );
-  }
-  const relative = path.relative(repoRoot, file).split(path.sep).join("/");
-  if (!Array.isArray(config?.creation_rules))
-    throw new Error(
-      ".sops.yaml requires creation_rules; run starci app secret init",
-    );
-  // A `.enc.yaml` member also matches a rule written for the legacy `.enc` spelling, so an app's existing .sops.yaml keeps
-  // sealing until `starci app secret recipients` rewrites it.
-  const spellings = [relative, ...(relative.endsWith(".enc.yaml") ? [relative.slice(0, -".yaml".length)] : [])];
-  const rule = config.creation_rules.find((entry) => {
+    let config; // reason: parsed YAML boundary, read from disk
     try {
-      return (
-        !entry.path_regex ||
-        spellings.some((spelling) =>
-          new RegExp(entry.path_regex).test(spelling) ||
-          new RegExp(entry.path_regex).test(spelling.replaceAll("/", "\\")))
-      );
-    } catch {
-      throw new Error(".sops.yaml has an invalid path_regex");
+        config = parseYaml(fs.readFileSync(path.join(repoRoot, ".sops.yaml"), "utf8"));
+    }
+    catch {
+        throw new Error("a valid .sops.yaml is required; run starci app secret init");
     }
-  });
-  const recipients =
-    typeof rule?.age === "string"
-      ? rule.age.split(",").map((value) => value.trim())
-      : [];
-  if (
-    !recipients.length ||
-    recipients.some((value) => !/^age1[a-z0-9]+$/.test(value))
-  )
-    throw new Error(
-      ".sops.yaml must supply public age recipients for this secret; run starci app secret init",
-    );
-  return recipients;
+    const relative = path.relative(repoRoot, file).split(path.sep).join("/");
+    if (!Array.isArray(config?.creation_rules))
+        throw new Error(".sops.yaml requires creation_rules; run starci app secret init");
+    // A `.enc.yaml` member also matches a rule written for the legacy `.enc` spelling, so an app's existing .sops.yaml keeps
+    // sealing until `starci app secret recipients` rewrites it.
+    const spellings = [relative, ...(relative.endsWith(".enc.yaml") ? [relative.slice(0, -".yaml".length)] : [])];
+    const rule = config.creation_rules.find((entry) => {
+        try {
+            return (!entry.path_regex ||
+                spellings.some((spelling) => new RegExp(entry.path_regex).test(spelling) ||
+                    new RegExp(entry.path_regex).test(spelling.replaceAll("/", "\\"))));
+        }
+        catch {
+            throw new Error(".sops.yaml has an invalid path_regex");
+        }
+    });
+    const recipients = typeof rule?.age === "string"
+        ? rule.age.split(",").map((value) => value.trim())
+        : [];
+    if (!recipients.length ||
+        recipients.some((value) => !/^age1[a-z0-9]+$/.test(value)))
+        throw new Error(".sops.yaml must supply public age recipients for this secret; run starci app secret init");
+    return recipients;
 }
-
 /** Resolve required tools without exposing subprocess output (which can contain private data). */
 export function secretTools(env, tools = {}) {
-  const sops = (tools.resolveSops ?? resolveSops)(env);
-  if (!sops)
-    throw new Error(
-      "sops is not installed; install SOPS and put sops on PATH (Windows: winget install Mozilla.SOPS)",
-    );
-  const resolve = tools.resolveRealTool ?? resolveRealTool;
-  const age = resolve("age", { env });
-  const keygen = resolve("age-keygen", { env });
-  if (!age || !keygen)
-    throw new Error(
-      "age or age-keygen is not installed; install age and put age and age-keygen on PATH",
-    );
-  return { sops, keygen, run: tools.runProgram ?? runProgram };
+    const sops = (tools.resolveSops ?? resolveSops)(env);
+    if (!sops)
+        throw new Error("sops is not installed; install SOPS and put sops on PATH (Windows: winget install Mozilla.SOPS)");
+    const resolve = tools.resolveRealTool ?? resolveRealTool;
+    const age = resolve("age", { env });
+    const keygen = resolve("age-keygen", { env });
+    if (!age || !keygen)
+        throw new Error("age or age-keygen is not installed; install age and put age and age-keygen on PATH");
+    return { sops, keygen, run: tools.runProgram ?? runProgram };
 }
-
 function readInitializationConfig(configFile) {
-  let config = {};
-  try {
-    if (fs.existsSync(configFile))
-      config = parseYaml(fs.readFileSync(configFile, "utf8")) ?? {};
-  } catch {
-    throw new Error(
-      ".sops.yaml is invalid; repair it before initializing secrets",
-    );
-  }
-  if (
-    typeof config !== "object" ||
-    Array.isArray(config) ||
-    (config.creation_rules !== undefined &&
-      !Array.isArray(config.creation_rules))
-  )
-    throw new Error(".sops.yaml must hold a creation_rules list");
-  return config;
+    let config = {}; // reason: parsed YAML boundary, read from disk
+    try {
+        if (fs.existsSync(configFile))
+            config = parseYaml(fs.readFileSync(configFile, "utf8")) ?? {};
+    }
+    catch {
+        throw new Error(".sops.yaml is invalid; repair it before initializing secrets");
+    }
+    if (typeof config !== "object" ||
+        Array.isArray(config) ||
+        (config.creation_rules !== undefined &&
+            !Array.isArray(config.creation_rules)))
+        throw new Error(".sops.yaml must hold a creation_rules list");
+    return config;
 }
-
 function existingInitializationRule(rules) {
-  const canonical = rules.find(
-    (rule) =>
-      [PATH_RULE, LEGACY_PATH_RULE].includes(rule?.path_regex) &&
-      typeof rule.age === "string" &&
-      rule.age.trim(),
-  );
-  return (
-    canonical ??
-    rules.find((rule) => {
-      if (typeof rule?.age !== "string" || !rule.age.trim()) return false;
-      try {
-        return (
-          !rule.path_regex ||
-          new RegExp(rule.path_regex).test(
-            ".starcistacks/production/secrets/app.enc",
-          )
-        );
-      } catch {
-        return false;
-      }
-    })
-  );
+    const canonical = rules.find((rule) => INITIALIZATION_PATH_RULES.includes(rule?.path_regex) &&
+        typeof rule.age === "string" &&
+        rule.age.trim() !== "");
+    return (canonical ??
+        rules.find((rule) => {
+            if (typeof rule?.age !== "string" || !rule.age.trim())
+                return false;
+            try {
+                return (!rule.path_regex ||
+                    new RegExp(rule.path_regex).test(".starcistacks/production/secrets/app.enc"));
+            }
+            catch {
+                return false;
+            }
+        }));
 }
-
 function legacyInitializationRecipient(repoRoot, env, platform, tool) {
-  const identity = secretRoots(env, platform).identity;
-  outsideRepository(repoRoot, identity);
-  privateDirectory(repoRoot, path.dirname(identity));
-  const held = claimFile(identity);
-  if (!held.ok)
-    throw new Error(
-      "the age identity is being initialized; retry after that operation settles",
-    );
-  try {
-    if (!fs.existsSync(identity)) {
-      const generated = tool.run(tool.keygen, ["-o", identity], {
-        env,
-        cwd: repoRoot,
-        stdio: ["ignore", "pipe", "pipe"],
-      });
-      if (generated.error || generated.status !== 0)
-        throw new Error(
-          "age-keygen could not create the private identity outside the repository",
-        );
+    const identity = secretRoots(env, platform).identity;
+    outsideRepository(repoRoot, identity);
+    privateDirectory(repoRoot, path.dirname(identity));
+    const held = claimFile(identity);
+    if (!held.ok)
+        throw new Error("the age identity is being initialized; retry after that operation settles");
+    try {
+        if (!fs.existsSync(identity)) {
+            const generated = tool.run(tool.keygen, ["-o", identity], {
+                env,
+                cwd: repoRoot,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            if (generated.error || generated.status !== 0)
+                throw new Error("age-keygen could not create the private identity outside the repository");
+        }
+        const stat = fs.lstatSync(identity);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1)
+            throw new Error("the age identity must be an ordinary private file");
+        if (process.platform !== "win32")
+            fs.chmodSync(identity, 0o600);
+        const publicKey = tool.run(tool.keygen, ["-y", identity], {
+            env,
+            cwd: repoRoot,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        if (publicKey.error || publicKey.status !== 0)
+            throw new Error("age-keygen could not read the public recipient from the existing identity");
+        const recipients = String(publicKey.stdout ?? "")
+            .trim()
+            .split(/\s+/);
+        if (!recipients.length ||
+            recipients.some((value) => !/^age1[a-z0-9]+$/.test(value)))
+            throw new Error("age-keygen returned an invalid public recipient");
+        return recipients.join(",");
+    }
+    finally {
+        held.release();
     }
-    const stat = fs.lstatSync(identity);
-    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1)
-      throw new Error("the age identity must be an ordinary private file");
-    if (process.platform !== "win32") fs.chmodSync(identity, 0o600);
-    const publicKey = tool.run(tool.keygen, ["-y", identity], {
-      env,
-      cwd: repoRoot,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    if (publicKey.error || publicKey.status !== 0)
-      throw new Error(
-        "age-keygen could not read the public recipient from the existing identity",
-      );
-    const recipients = String(publicKey.stdout ?? "")
-      .trim()
-      .split(/\s+/);
-    if (
-      !recipients.length ||
-      recipients.some((value) => !/^age1[a-z0-9]+$/.test(value))
-    )
-      throw new Error("age-keygen returned an invalid public recipient");
-    return recipients.join(",");
-  } finally {
-    held.release();
-  }
 }
-
 function initializationRecipient(repoRoot, env, platform, tool, tools) {
-  const selectedEnv = ageIdentityEnv(repoRoot, env, tools);
-  if (!Object.keys(selectedEnv).some((name) => /^SOPS_AGE_KEY$/i.test(name)))
-    return legacyInitializationRecipient(repoRoot, env, platform, tool);
-  const result = selectedAgeRecipient({
-    env: selectedEnv,
-    cwd: repoRoot,
-    invocation: {
-      runProgram: tool.run,
-      resolveRealTool: tools?.resolveRealTool ?? resolveRealTool,
-    },
-  });
-  if (!result.ok)
-    throw new Error(`SOPS_AGE_KEY public recipient could not be derived (${result.reason})`);
-  return result.publicRecipient;
+    const selectedEnv = ageIdentityEnv(repoRoot, env, tools);
+    if (!Object.keys(selectedEnv).some((name) => /^SOPS_AGE_KEY$/i.test(name)))
+        return legacyInitializationRecipient(repoRoot, env, platform, tool);
+    const result = selectedAgeRecipient({
+        env: selectedEnv,
+        cwd: repoRoot,
+        invocation: {
+            runProgram: tool.run,
+            resolveRealTool: tools?.resolveRealTool ?? resolveRealTool,
+        },
+    });
+    if (!result.ok)
+        throw new Error(`SOPS_AGE_KEY public recipient could not be derived (${result.reason})`);
+    return result.publicRecipient;
 }
-
 /**
  * The public recipient of the owner's age identity, as localAgeIdentity finds it (`host` its last source). Only an inline
  * SOPS_AGE_KEY is derived; with none the caller names the recipient itself.
  */
-export function ownerRecipient(repoRoot, env, { platform, tools, host = null }) {
-  const local = localAgeIdentity(repoRoot, env, tools, host);
-  if (!Object.keys(local.env).some((name) => /^SOPS_AGE_KEY$/i.test(name)))
-    throw new Error(
-      `no SOPS_AGE_KEY found (looked in the environment${local.looked.length ? `, ${local.looked.join(", ")}` : ""}); name the owner's public recipient (age1...) instead of owner`,
-    );
-  return initializationRecipient(repoRoot, local.env, platform, secretTools(env, tools), tools);
+export function ownerRecipient(repoRoot, env, { platform, tools, host = null, }) {
+    const local = localAgeIdentity(repoRoot, env, tools, host);
+    if (!Object.keys(local.env).some((name) => /^SOPS_AGE_KEY$/i.test(name)))
+        throw new Error(`no SOPS_AGE_KEY found (looked in the environment${local.looked.length ? `, ${local.looked.join(", ")}` : ""}); name the owner's public recipient (age1...) instead of owner`);
+    return initializationRecipient(repoRoot, local.env, platform, secretTools(env, tools), tools);
 }
-
 /**
- * `starci app secret recipients <env> [--add <age1...|owner>] [--remove <age1...|owner>]`: prints the public recipients a
- * member of the environment is sealed to, or rewrites the environment's own rule of the app's managed .sops.yaml (one rule per
- * environment, written before the app-wide rule, public keys only). `owner` is the owner identity's recipient (ownerRecipient).
- * A member sealed before keeps its recipients until it is sealed again.
+ * `starci app secret recipients --env <env> [--add <age1...|owner>] [--remove <age1...|owner>] [--execute]`: prints the public
+ * recipients a member of the environment is sealed to, or (with --add/--remove) says what the environment's own rule of the
+ * app's managed .sops.yaml would become and, only with --execute, rewrites it (one rule per environment, written before the
+ * app-wide rule, public keys only). `owner` is the owner identity's recipient (ownerRecipient). A member sealed before keeps
+ * its recipients until it is sealed again. `execute` defaults to true for the library callers (stack/server-key.mjs); the verb
+ * passes the flag, so a dry run is the default there.
  */
-export function environmentRecipients(repoRoot, environment, { add = [], remove = [], owner, stdout }) {
-  const configFile = path.join(repoRoot, ".sops.yaml");
-  const config = readInitializationConfig(configFile);
-  const rules = Array.isArray(config.creation_rules) ? config.creation_rules : [];
-  const probe = path.join(repoRoot, ".starcistacks", environment, "secrets", "member.enc.yaml");
-  let current = [];
-  try { current = configuredRecipients(repoRoot, probe); } catch { current = []; }
-  if (!add.length && !remove.length) {
-    stdout(`${environment}: ${current.join(", ") || "no rule names a recipient; run starci app secret init"}\n`);
+export function environmentRecipients(repoRoot, environment, { add = [], remove = [], execute = true, owner, stdout, }) {
+    const configFile = path.join(repoRoot, ".sops.yaml");
+    const config = readInitializationConfig(configFile);
+    const rules = Array.isArray(config.creation_rules) ? config.creation_rules : [];
+    const probe = path.join(repoRoot, ".starcistacks", environment, "secrets", "member.enc.yaml");
+    let current = [];
+    try {
+        current = configuredRecipients(repoRoot, probe);
+    }
+    catch {
+        current = [];
+    }
+    if (!add.length && !remove.length) {
+        stdout(`${environment}: ${current.join(", ") || "no rule names a recipient; run starci app secret init"}\n`);
+        return 0;
+    }
+    let ownerValue;
+    const resolve = (value) => {
+        if (value !== "owner")
+            return value;
+        ownerValue ??= owner();
+        return ownerValue;
+    };
+    const next = [...current];
+    for (const value of add.map(resolve)) {
+        if (!/^age1[a-z0-9]+$/u.test(value))
+            throw new Error(`${value} is not a public age recipient (age1...)`);
+        if (!next.includes(value))
+            next.push(value);
+    }
+    for (const value of remove.map(resolve)) {
+        const at = next.indexOf(value);
+        if (at < 0)
+            throw new Error(`${environment} is not sealed to ${value}`);
+        next.splice(at, 1);
+    }
+    if (!next.length)
+        throw new Error(`${environment} keeps at least one recipient`);
+    const regex = environmentRule(environment);
+    const own = rules.findIndex((rule) => rule?.path_regex === regex);
+    if (own >= 0)
+        rules[own] = { ...rules[own], age: next.join(",") };
+    else {
+        const appWide = rules.findIndex((rule) => !rule?.path_regex || INITIALIZATION_PATH_RULES.includes(rule.path_regex));
+        rules.splice(appWide < 0 ? rules.length : appWide, 0, { path_regex: regex, age: next.join(",") });
+    }
+    if (!execute) {
+        stdout(`dry run: would set the ${environment} recipients of .sops.yaml to ${next.join(", ")} (now ${current.join(", ") || "none"}); add --execute\n`);
+        return 0;
+    }
+    config.creation_rules = rules;
+    fs.writeFileSync(configFile, `# Managed by starci app secret init and recipients: one rule per environment, public age recipients only.\n${stringifyYaml(config)}`);
+    stdout(`${environment}: ${next.join(", ")}; a member sealed before keeps its recipients until it is sealed again (starci app secret migrate --env ${environment} <member> --execute)\n`);
     return 0;
-  }
-  let ownerValue;
-  const resolve = (value) => {
-    if (value !== "owner") return value;
-    ownerValue ??= owner();
-    return ownerValue;
-  };
-  const next = [...current];
-  for (const value of add.map(resolve)) {
-    if (!/^age1[a-z0-9]+$/u.test(value)) throw new Error(`${value} is not a public age recipient (age1...)`);
-    if (!next.includes(value)) next.push(value);
-  }
-  for (const value of remove.map(resolve)) {
-    const at = next.indexOf(value);
-    if (at < 0) throw new Error(`${environment} is not sealed to ${value}`);
-    next.splice(at, 1);
-  }
-  if (!next.length) throw new Error(`${environment} keeps at least one recipient`);
-  const regex = environmentRule(environment);
-  const own = rules.findIndex((rule) => rule?.path_regex === regex);
-  if (own >= 0) rules[own] = { ...rules[own], age: next.join(",") };
-  else {
-    const appWide = rules.findIndex((rule) => !rule?.path_regex || [PATH_RULE, LEGACY_PATH_RULE].includes(rule.path_regex));
-    rules.splice(appWide < 0 ? rules.length : appWide, 0, { path_regex: regex, age: next.join(",") });
-  }
-  config.creation_rules = rules;
-  fs.writeFileSync(
-    configFile,
-    `# Managed by starci app secret init and recipients: one rule per environment, public age recipients only.\n${stringifyYaml(config)}`,
-  );
-  stdout(
-    `${environment}: ${next.join(", ")}; a member sealed before keeps its recipients until it is sealed again (starci app secret migrate ${environment} <member> --execute)\n`,
-  );
-  return 0;
 }
-
 /** Reuse an existing matching age rule; initialization must not rotate an app's recipient. */
-export function initializeSecrets(repoRoot, { env, platform, tools, stdout, host = null }) {
-  const configFile = path.join(repoRoot, ".sops.yaml");
-  const config = readInitializationConfig(configFile);
-  const rules = config.creation_rules ?? [];
-  const existing = existingInitializationRule(rules);
-  if (
-    existing?.age
-      .split(",")
-      .some((value) => !/^age1[a-z0-9]+$/.test(value.trim()))
-  )
-    throw new Error(
-      ".sops.yaml must name valid public age recipients; initialization never prints private key material",
-    );
-  const localEnv = localAgeIdentity(repoRoot, {}, tools, host).env;
-  const selectedEnv = ageIdentityEnv(repoRoot, existing ? env : { ...env, ...localEnv }, tools);
-  if (!existing && !Object.keys(localEnv).some((name) => /^SOPS_AGE_KEY$/i.test(name))) {
-    const initialized = initializeAppIdentity(repoRoot, { tools });
-    materializeDeclaredPlaceholders(repoRoot, { recipient: initialized.recipient, processEnv: selectedEnv });
-    stdout('secrets initialized; public recipient: ' + initialized.recipient + '\n');
+export function initializeSecrets(repoRoot, { env, platform, tools, stdout, host = null, }) {
+    const configFile = path.join(repoRoot, ".sops.yaml");
+    const config = readInitializationConfig(configFile);
+    const rules = config.creation_rules ?? [];
+    const existing = existingInitializationRule(rules);
+    if (existing?.age
+        .split(",")
+        .some((value) => !/^age1[a-z0-9]+$/.test(value.trim())))
+        throw new Error(".sops.yaml must name valid public age recipients; initialization never prints private key material");
+    const localEnv = localAgeIdentity(repoRoot, {}, tools, host).env;
+    const selectedEnv = ageIdentityEnv(repoRoot, existing ? env : { ...env, ...localEnv }, tools);
+    if (!existing && !Object.keys(localEnv).some((name) => /^SOPS_AGE_KEY$/i.test(name))) {
+        const initialized = initializeAppIdentity(repoRoot, { tools });
+        materializeDeclaredPlaceholders(repoRoot, { recipient: initialized.recipient, processEnv: selectedEnv });
+        stdout('secrets initialized; public recipient: ' + initialized.recipient + '\n');
+        return 0;
+    }
+    const tool = secretTools(env, tools);
+    const inline = Object.keys(selectedEnv).some((name) => /^SOPS_AGE_KEY$/i.test(name));
+    const derived = existing && !inline ? existing.age : initializationRecipient(repoRoot, selectedEnv, platform, tool, tools);
+    const recipient = existing?.age ?? derived;
+    const exact = rules.findIndex((rule) => INITIALIZATION_PATH_RULES.includes(rule?.path_regex));
+    if (exact >= 0)
+        rules[exact] = { ...rules[exact], age: recipient };
+    // SOPS uses the first matching rule: keep any existing environment-specific recipients in force.
+    else
+        rules.push({ path_regex: PATH_RULE, age: recipient });
+    config.creation_rules = rules;
+    fs.writeFileSync(configFile, `# Initialized by starci app secret init; private age identities stay outside Git.\n${stringifyYaml(config)}`);
+    materializeDeclaredPlaceholders(repoRoot, {
+        recipient,
+        recipientsForFile: (file) => configuredRecipients(repoRoot, file),
+        processEnv: selectedEnv,
+        sops: { seal: (request) => defaultSops(selectedEnv, repoRoot, platform, tools).seal(request) },
+    });
+    stdout(`secrets initialized; public recipient: ${recipient}\n`);
+    if (existing)
+        stdout("existing app recipient retained; use its matching age identity for decryption\n");
     return 0;
-  }
-  const tool = secretTools(env, tools);
-  const inline = Object.keys(selectedEnv).some((name) => /^SOPS_AGE_KEY$/i.test(name));
-  const derived = existing && !inline ? existing.age : initializationRecipient(repoRoot, selectedEnv, platform, tool, tools);
-  const recipient = existing?.age ?? derived;
-  const exact = rules.findIndex((rule) => [PATH_RULE, LEGACY_PATH_RULE].includes(rule?.path_regex));
-  if (exact >= 0) rules[exact] = { ...rules[exact], age: recipient };
-  // SOPS uses the first matching rule: keep any existing environment-specific recipients in force.
-  else rules.push({ path_regex: PATH_RULE, age: recipient });
-  config.creation_rules = rules;
-  fs.writeFileSync(
-    configFile,
-    `# Initialized by starci app secret init; private age identities stay outside Git.\n${stringifyYaml(config)}`,
-  );
-  materializeDeclaredPlaceholders(repoRoot, {
-    recipient,
-    recipientsForFile: (file) => configuredRecipients(repoRoot, file),
-    processEnv: selectedEnv,
-    sops: { seal: (request) => defaultSops(selectedEnv, repoRoot, platform, tools).seal(request) },
-  });
-  stdout(`secrets initialized; public recipient: ${recipient}\n`);
-  if (existing)
-    stdout(
-      "existing app recipient retained; use its matching age identity for decryption\n",
-    );
-  return 0;
 }