@starci/hfs 4.2.17 → 4.4.0

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

@@ -0,0 +1,300 @@
+// secret-init.mjs — initialize the public app rule and an age identity outside Git.
+import fs from "node:fs";
+import path from "node:path";
+import { parseYaml, stringifyYaml } from "../../engine/yaml.mjs";
+import { secretEnv } from "../../engine/secrets.mjs";
+import { resolveSops } from "../api/sops/resolve-sops.mjs";
+import { selectedAgeRecipient } from "../api/sops/selected-age-recipient.mjs";
+import { resolveRealTool } from "../api/process/resolve-real-tool.mjs";
+import { runProgram } from "../api/process/run-program.mjs";
+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 {
+  outsideRepository,
+  privateDirectory,
+  secretRoots,
+} from "./secret-files.mjs";
+
+const PATH_RULE = String.raw`\.starcistacks[/\\][^/\\]+[/\\]secrets[/\\][^/\\]+\.enc$`;
+const AGE_IDENTITY_NAME = /^SOPS_AGE_KEY(?:_FILE)?$/i;
+
+/** 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);
+  }
+}
+
+/** Load host-local age selections below the explicit environment, without copying any other credentials. */
+export function ageIdentityEnv(repoRoot, env, tools) {
+  const load = tools?.secretEnv ?? secretEnv;
+  let resolved = {};
+  try {
+    resolved = load(path.join(repoRoot, ".claude"), env) ?? {};
+  } catch {
+    return { ...env };
+  }
+  const own = new Set(Object.keys(env).map((name) => name.toUpperCase()));
+  const local = Object.fromEntries(
+    Object.entries(resolved).filter(
+      ([name]) => AGE_IDENTITY_NAME.test(name) && !own.has(name.toUpperCase()),
+    ),
+  );
+  return { ...env, ...local };
+}
+
+/** 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",
+    );
+  const rule = config.creation_rules.find((entry) => {
+    try {
+      return (
+        !entry.path_regex ||
+        new RegExp(entry.path_regex).test(relative) ||
+        new RegExp(entry.path_regex).test(relative.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 };
+}
+
+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;
+}
+
+function existingInitializationRule(rules) {
+  const canonical = rules.find(
+    (rule) =>
+      rule?.path_regex === PATH_RULE &&
+      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 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;
+}
+
+/** Reuse an existing matching age rule; initialization must not rotate an app's recipient. */
+export function initializeSecrets(repoRoot, { env, platform, tools, stdout }) {
+  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 = ageIdentityEnv(repoRoot, {}, tools);
+  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) => rule?.path_regex === PATH_RULE);
+  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;
+}

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

@@ -0,0 +1,100 @@
+// secret-output.mjs - list and materialize secret names and private KEY files.
+import fs from "node:fs";
+import path from "node:path";
+import { byCodeUnit } from "../lib/list.mjs";
+import { materializedDirectory, writeSecretFile } from "./secret-files.mjs";
+import { envelopeOf, validateKey } from "./secret-document.mjs";
+import { fileOf, readMap, sealedFiles } from "./secret-store.mjs";
+import { SecretError, publicStorage } from "./secret-errors.mjs";
+
+function validateWindowsKeys(map) {
+  const names = new Set();
+  for (const key of Object.keys(map)) {
+    const normalized = key.toUpperCase();
+    if (names.has(normalized))
+      throw new SecretError(
+        "KEY names differing only by case cannot be materialized on Windows",
+      );
+    if (/^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/.test(normalized))
+      throw new SecretError(
+        "a KEY uses a reserved Windows file name and cannot be materialized",
+      );
+    names.add(normalized);
+  }
+}
+
+function exportValues(
+  map,
+  {
+    repoRoot,
+    environment,
+    env,
+    platform,
+    stdout,
+    fileOutput = stdout,
+    reveal = false,
+    toFile = true,
+  },
+) {
+  if (toFile && platform === "win32") validateWindowsKeys(map);
+  const directory = toFile
+    ? publicStorage(() =>
+        materializedDirectory(repoRoot, environment, env, platform),
+      )
+    : null;
+  for (const key of Object.keys(map).sort(byCodeUnit)) {
+    if (toFile) {
+      const file = publicStorage(() =>
+        writeSecretFile(directory, key, map[key]),
+      );
+      fileOutput(`${key}_FILE=${file}\n`);
+    }
+    if (reveal) stdout(`${key}=${map[key]}\n`);
+  }
+  return 0;
+}
+
+export function listSecrets(directory, stdout) {
+  const keys = new Set();
+  for (const name of sealedFiles(directory)) {
+    for (const item of envelopeOf(
+      fs.readFileSync(path.join(directory, name), "utf8"),
+    ).keys) {
+      validateKey(item);
+      keys.add(item);
+    }
+  }
+  for (const item of [...keys].sort(byCodeUnit)) stdout(`${item}\n`);
+  return 0;
+}
+
+export function materializeSecrets(directory, sops, output) {
+  const map = Object.create(null);
+  for (const name of sealedFiles(directory)) {
+    for (const [item, value] of Object.entries(
+      readMap(fileOf(directory, name.slice(0, -4)), sops),
+    )) {
+      if (Object.hasOwn(map, item))
+        throw new SecretError(
+          `duplicate KEY ${item} across secret slugs; each materialized KEY needs one owner`,
+        );
+      map[item] = value;
+    }
+  }
+  return exportValues(map, output);
+}
+
+export function getSecret(file, key, sops, opts, output, stderr) {
+  let map = readMap(file, sops);
+  if (key !== undefined) {
+    if (!Object.hasOwn(map, key))
+      throw new SecretError(`the secret has no KEY ${key}`);
+    map = { [key]: map[key] };
+  }
+  return exportValues(map, {
+    ...output,
+    fileOutput: stderr,
+    reveal: opts.reveal,
+    toFile: opts["to-file"] === true,
+  });
+}

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

@@ -0,0 +1,130 @@
+// secret-sops.mjs - runtime SOPS adapter and age identity selection.
+import fs from "node:fs";
+import path from "node:path";
+import { runProgram } from "../api/process/run-program.mjs";
+import { resolveRealTool } from "../api/process/resolve-real-tool.mjs";
+import { decrypt as sopsDecrypt } from "../api/sops/decrypt.mjs";
+import { seal as sopsSeal } from "../api/sops/seal.mjs";
+import { invocationDir } from "../lib/roots.mjs";
+import { envelopeOf } from "./secret-document.mjs";
+import { ageIdentityEnv, configuredRecipients, secretTools } from "./secret-init.mjs";
+import { outsideRepository, secretRoots } from "./secret-files.mjs";
+import { SecretError, publicStorage } from "./secret-errors.mjs";
+
+const sopsInvocation = Object.freeze({ runProgram, resolveRealTool });
+const AGE_IDENTITY_NAME = /^SOPS_AGE_KEY(?:_FILE)?$/i;
+
+/** The default sops seam: the runtime's sops api, which finds the binary on this machine. */
+export function defaultSops(
+  env = process.env,
+  repoRoot = invocationDir(),
+  platform = process.platform,
+  tools,
+) {
+  const { sops: binary } = publicStorage(() => secretTools(env, tools));
+  const selectedEnv = ageIdentityEnv(repoRoot, env, tools);
+  const invocation = {
+    runProgram: tools?.runProgram ?? sopsInvocation.runProgram,
+    resolveRealTool: tools?.resolveRealTool ?? sopsInvocation.resolveRealTool,
+  };
+  const checkIdentity = (file) =>
+    publicStorage(() => {
+      outsideRepository(repoRoot, file);
+      if (fs.existsSync(file)) {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1)
+          throw new Error(
+            "the age identity must be an ordinary private file without hard links",
+          );
+      }
+    });
+  for (const [name, value] of Object.entries(selectedEnv))
+    if (/^SOPS_AGE_KEY_FILE$/i.test(name) && value) {
+      if (!path.isAbsolute(value))
+        throw new SecretError(
+          "SOPS_AGE_KEY_FILE must be an absolute path outside the repository",
+        );
+      checkIdentity(value);
+    }
+  if (
+    !Object.keys(selectedEnv).some((name) => AGE_IDENTITY_NAME.test(name))
+  ) {
+    const identity = secretRoots(env, platform).identity;
+    checkIdentity(identity);
+    if (fs.existsSync(identity)) selectedEnv.SOPS_AGE_KEY_FILE = identity;
+  }
+  const refuse = (what, result) => {
+    if (result.error?.identityRefusal)
+      return Object.assign(new SecretError(result.error.message), {
+        identityRefusal: result.error.identityRefusal,
+      });
+    if (result.error?.code === "SOPS_MISSING")
+      return new SecretError(result.error.message);
+    return new SecretError(
+      `sops could not ${what} (exit ${String(result.status)})`,
+    );
+  };
+  return {
+    decrypt(file, format) {
+      const result = sopsDecrypt(
+        binary,
+        ["decrypt", "--input-type", format, "--output-type", "dotenv", file],
+        { env: selectedEnv, cwd: repoRoot, invocation },
+      );
+      if (result.status !== 0)
+        throw refuse(
+          `decrypt ${path.basename(file)}; is the age identity installed?`,
+          result,
+        );
+      const map = Object.create(null);
+      for (const line of String(result.stdout).split(/\r?\n/u)) {
+        if (!line || line.startsWith("#")) continue;
+        const match = /^([A-Za-z_]\w*)=(.*)$/u.exec(line);
+        if (!match || Object.hasOwn(map, match[1]))
+          throw new SecretError("sops returned an invalid dotenv document");
+        map[match[1]] = match[2].replaceAll(String.raw`\n`, "\n");
+      }
+      return map;
+    },
+    /**
+     * The ssh key and known_hosts of the deploy custody. A classic sops BINARY envelope (one `data` property) yields the file itself;
+     * a JSON envelope under another property name (privateKey, knownHosts, ciPrivateKey) yields the JSON text of its properties,
+     * which the stack remote code unwraps by name.
+     */
+    decryptBinary(file) {
+      const envelope = envelopeOf(fs.readFileSync(file, "utf8"));
+      const classic =
+        envelope.format === "json" &&
+        envelope.keys.length === 1 &&
+        envelope.keys[0] === "data";
+      const types = classic
+        ? ["binary", "binary"]
+        : [envelope.format, "json"];
+      const result = sopsDecrypt(
+        binary,
+        ["decrypt", "--input-type", types[0], "--output-type", types[1], file],
+        { env: selectedEnv, cwd: repoRoot, invocation },
+      );
+      if (result.status !== 0)
+        throw refuse(
+          `decrypt ${path.basename(file)}; is the age identity installed?`,
+          result,
+        );
+      return String(result.stdout);
+    },
+    seal(request) {
+      const recipients = request.recipients.length
+        ? request.recipients
+        : publicStorage(() =>
+            configuredRecipients(repoRoot, request.filenameOverride),
+          );
+      const result = sopsSeal(
+        binary,
+        { ...request, recipients },
+        { env: selectedEnv, cwd: repoRoot, invocation },
+      );
+      if (result.status !== 0) throw refuse("seal the secret", result);
+      return result.stdout;
+    },
+  };
+}

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

@@ -0,0 +1,163 @@
+// secret-store.mjs - sealed secret paths and atomic named-value updates.
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { claimFile } from "../api/fs/claim-file.mjs";
+import { isSopsEnvelope } from "../lib/sops-envelope.mjs";
+import { byCodeUnit } from "../lib/list.mjs";
+import {
+  envelopeOf,
+  plaintextOf,
+  validateKey,
+  validateMap,
+} from "./secret-document.mjs";
+import { defaultSops } from "./secret-sops.mjs";
+import { SecretError } from "./secret-errors.mjs";
+
+const SLUG = /^[a-z0-9][a-z0-9-]*$/u;
+
+/** The directory of the sealed secrets of the app at `repoRoot` for `env`; the one env that has secrets when none is named. */
+export function secretsDirectory(repoRoot, env) {
+  const stacks = path.join(repoRoot, ".starcistacks");
+  if (env) {
+    if (!/^[a-z0-9][a-z0-9-]*$/u.test(env))
+      throw new SecretError(`--env ${env} is not an environment name`);
+    return path.join(stacks, env, "secrets");
+  }
+  if (!fs.existsSync(stacks))
+    throw new SecretError(
+      "this app has no .starcistacks; run starci app secret at the app root, or pass --cwd",
+    );
+  const withSecrets = fs
+    .readdirSync(stacks, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() &&
+        fs.existsSync(path.join(stacks, entry.name, "secrets")),
+    )
+    .map((entry) => entry.name);
+  if (withSecrets.length === 1)
+    return path.join(stacks, withSecrets[0], "secrets");
+  throw new SecretError(
+    withSecrets.length === 0
+      ? "no environment of .starcistacks has a secrets folder; pass --env to create the first secret"
+      : `more than one environment has secrets (${withSecrets.join(", ")}); pass --env`,
+  );
+}
+
+export const fileOf = (directory, slug) => {
+  if (!SLUG.test(slug ?? ""))
+    throw new SecretError(
+      `${slug === undefined ? "a secret name" : slug} is not a secret slug: lowercase letters, digits and dashes`,
+    );
+  return path.join(directory, `${slug}.enc`);
+};
+
+/** Build and validate a replacement envelope without publishing it. */
+function sealSecretMap({ file, values, age, sops }) {
+  let map = Object.create(null);
+  let recipients = age;
+  if (fs.existsSync(file)) {
+    const envelope = envelopeOf(fs.readFileSync(file, "utf8"));
+    map = sops.decrypt(file, envelope.format);
+    if (!age.length) recipients = envelope.recipients;
+  }
+  validateMap(map);
+  map = { ...map, ...values };
+  const sealed = sops.seal({ inputType: "dotenv", plaintext: plaintextOf("dotenv", map), recipients, filenameOverride: file });
+  let parsed;
+  try { parsed = envelopeOf(sealed); }
+  catch { throw new SecretError("sops returned an invalid sealed document"); }
+  if (!isSopsEnvelope(sealed) || parsed.keys.length !== Object.keys(map).length || !parsed.keys.every((key) => Object.hasOwn(map, key)))
+    throw new SecretError("sops returned an invalid sealed document");
+  return sealed;
+}
+
+/** Publish through an explicit file owner, or the canonical atomic replace. */
+function publishSealed(file, sealed, write) {
+  if (write) { write(file, sealed); return; }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = path.join(path.dirname(file), "." + path.basename(file) + "-" + randomUUID() + ".tmp");
+  try {
+    fs.writeFileSync(temporary, sealed, { flag: "wx", mode: 0o600, flush: true });
+    fs.renameSync(temporary, file);
+  } finally {
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+  }
+}
+
+function underClaim(file, action) {
+  const held = claimFile(path.resolve(file));
+  if (!held.ok)
+    throw new SecretError("the sealed secret is being updated; retry after that write settles");
+  try {
+    action();
+  } finally { held.release(); }
+}
+
+/** Replace one existing sealed member with an already validated envelope: same claim and atomic publish as set. */
+export const replaceSealed = (file, sealed) => underClaim(file, () => publishSealed(file, sealed));
+
+/** Delete one sealed member under the writer claim. */
+export const deleteSealed = (file) => underClaim(file, () => fs.unlinkSync(file));
+
+/** Seal named values; a supplied writer owns its own claim and rollback (the fresh-app scaffold). */
+export function writeSecret({ file, values, age, sops, write }) {
+  for (const key of Object.keys(values)) validateKey(key);
+  const held = write ? { ok: true, release() {} } : claimFile(path.resolve(file));
+  if (!held.ok)
+    throw new SecretError("the sealed secret is being updated; retry after that write settles");
+  try {
+    publishSealed(file, sealSecretMap({ file, values, age, sops }), write);
+  } finally { held.release(); }
+}
+
+/** Update named keys through the same canonical sealed-secret owner used by the CLI. */
+export function setSecretValues(
+  repoRoot,
+  { slug, values, env = null },
+  { sops = null, age = [], processEnv = process.env, write } = {},
+) {
+  const directory = secretsDirectory(repoRoot, env);
+  const file = fileOf(directory, slug);
+  if (
+    !values ||
+    typeof values !== "object" ||
+    Array.isArray(values) ||
+    !Object.keys(values).length
+  )
+    throw new SecretError("secret update requires named values");
+  for (const value of Object.values(values))
+    if (typeof value !== "string" || value === "")
+      throw new SecretError("secret values must be nonempty strings");
+  writeSecret({
+    file,
+    values,
+    age,
+    sops: sops ?? defaultSops(processEnv, repoRoot),
+    write,
+  });
+  return { file, via: "sealed-secret" };
+}
+
+export function sealedFiles(directory) {
+  return fs.existsSync(directory)
+    ? fs
+        .readdirSync(directory)
+        .filter((name) => name.endsWith(".enc"))
+        .sort(byCodeUnit)
+    : [];
+}
+
+export function readMap(file, sops) {
+  if (!fs.existsSync(file))
+    throw new SecretError(
+      "the requested secret is not sealed in this environment",
+    );
+  const map = sops.decrypt(
+    file,
+    envelopeOf(fs.readFileSync(file, "utf8")).format,
+  );
+  validateMap(map);
+  return map;
+}