@starci/hfs 4.2.17 → 4.3.0

package/runtime/scripts/hfs/rules/stacks.mjs

@@ -1,14 +1,16 @@
-// stacks.mjs - HFS_STACKS_SHAPE (R10): `.starcistacks` has the standard shape and the host Sonar owner.
+// stacks.mjs - HFS_STACKS_SHAPE (R10): standard stack shape, Sonar owner and deployment runtime consistency.
 //   - every tracked path under the app root's `.starcistacks/` is one the app.starcistacks slot allows (its `allows` list is the shape:
-//     application-stacks.yaml and <env>/{README.md, environment.json, infra/{compose,k8s,terraform}, runtime/{config,env},
+//     application-stacks.yaml and <env>/{README.md, environment.json, infra/{compose,swarm,k8s,terraform}, runtime/{config,env},
 //     secrets/<slug>.enc, seeds}); a `.enc` outside <env>/secrets/ is never allowed, `runtime/files/`, a root `DESIGN.md`,
 //     `deployment.json` and `k8s/` are not in the list, so they fall out of it;
 //   - the declaration (read by scripts/lib/stack-declaration.mjs, the one reader of it) states a sonar service, a local
 //     Sonar is owned by the host (`stack.owner: host`, root `.claude/ext/sonar`).
-// The declaration's services contract (custody, CI wiring, project keys) stays check-starcistacks's; this file judges shape only.
+// The lite overlay admits Swarm compute and managed Supabase backing. Runtime rules are shared with the stack gates.
+// The declaration's quality/delivery services contract (custody, CI wiring, project keys) stays check-starcistacks's.
 import { braceVariants, globExpression } from '../../lib/glob.mjs';
 import { declaredStack, findStackDeclaration, STACK_ROOT, text } from '../../lib/stack-declaration.mjs';
 import { found } from './read.mjs';
+import { hostCrontabFindings, stacksRuntimeFindings } from './stacks-runtime.mjs';
 
 const STACKS_SHAPE = 'HFS_STACKS_SHAPE';
 const STACKS_SLOT = 'app.starcistacks';
@@ -30,11 +32,10 @@ function treeFindings(files, allowed, prefix) {
   return findings;
 }
 
-function declarationFindings(repoRoot, files, prefix) {
+function declarationFindings(files, prefix, declaration) {
   const declared = `${prefix}application-stacks.yaml`;
   if (!files.includes(declared)) return [];
   const findings = [];
-  const declaration = findStackDeclaration(repoRoot);
   if (declaration.error) return [shapeFinding(declared, `${declared} cannot be read: ${declaration.error}`)];
   const services = declaration.doc?.services;
   if (services === undefined || typeof services.sonar !== 'object' || services.sonar === null) {
@@ -55,7 +56,11 @@ export function stacksFindings({ repoRoot, files, resolver }) {
   const slot = resolver.slot(STACKS_SLOT);
   if (!slot) return [];
   const prefix = `${STACK_ROOT}/`;
-  const findings = treeFindings(files, allowedExpressions(slot.allows ?? []), prefix);
-  findings.push(...declarationFindings(repoRoot, files, prefix));
-  return findings;
+  const declaration = findStackDeclaration(repoRoot);
+  return [
+    ...treeFindings(files, allowedExpressions(slot.allows ?? []), prefix),
+    ...declarationFindings(files, prefix, declaration),
+    ...hostCrontabFindings({ repoRoot, files }),
+    ...(declaration.doc ? stacksRuntimeFindings({ repoRoot, files, doc: declaration.doc, edition: resolver.repo?.edition }) : []),
+  ];
 }

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

@@ -0,0 +1,97 @@
+// secret-document.mjs - envelope inspection, plaintext serialization and named-value validation.
+import { SecretError } from "./secret-errors.mjs";
+
+const KEY = /^[A-Za-z_]\w*$/u;
+const WHITESPACE = String.raw`\s`;
+const REQUIRED_INDENT = `${WHITESPACE}+`;
+const OPTIONAL_DASH = "-?";
+const OPTIONAL_SPACING = `${WHITESPACE}*`;
+const RECIPIENT_NAME = "recipient:";
+const RECIPIENT_VALUE = String.raw`(\S+)`;
+const RECIPIENT_LINE = new RegExp(
+  `^${REQUIRED_INDENT}${OPTIONAL_DASH}${OPTIONAL_SPACING}${RECIPIENT_NAME}${OPTIONAL_SPACING}${RECIPIENT_VALUE}`,
+  "gmu",
+);
+
+/** The envelope format of a sealed secret, read from its text: json, yaml or dotenv. */
+export function formatOf(text) {
+  const body = String(text).trimStart();
+  if (body.startsWith("{")) return "json";
+  if (/^sops:\s*$/mu.test(text)) return "yaml";
+  return "dotenv";
+}
+
+/** The key names a sealed document holds and the age recipients it is sealed to, read without decrypting anything. */
+export function envelopeOf(text) {
+  const format = formatOf(text);
+  if (format === "json") {
+    const doc = JSON.parse(text);
+    return {
+      format,
+      keys: Object.keys(doc).filter((name) => name !== "sops"),
+      recipients: (doc.sops?.age ?? [])
+        .map((entry) => entry.recipient)
+        .filter(Boolean),
+    };
+  }
+  if (format === "yaml") {
+    const keys = [...text.matchAll(/^([A-Za-z_]\w*):/gmu)]
+      .map((match) => match[1])
+      .filter((name) => name !== "sops");
+    return {
+      format,
+      keys,
+      recipients: [...text.matchAll(RECIPIENT_LINE)].map((match) => match[1]),
+    };
+  }
+  const keys = [...text.matchAll(/^([A-Za-z_]\w*)=/gmu)]
+    .map((match) => match[1])
+    .filter((name) => !name.startsWith("sops_"));
+  return {
+    format,
+    keys,
+    recipients: [
+      ...text.matchAll(/^sops_age__list_\d+__map_recipient=(\S+)/gmu),
+    ].map((match) => match[1]),
+  };
+}
+
+/** SOPS dotenv escapes LF as backslash-n; literal backslash-n has no distinct representation. */
+export function plaintextOf(format, map) {
+  if (format === "json") return `${JSON.stringify(map)}\n`;
+  if (format === "yaml")
+    return (
+      Object.entries(map)
+        .map(([name, value]) => name + ": " + JSON.stringify(value))
+        .join("\n") + "\n"
+    );
+  for (const value of Object.values(map))
+    if (/\r|\\n/u.test(value))
+      throw new SecretError(
+        "dotenv cannot preserve a carriage return or literal backslash-n; use an LF line break instead",
+      );
+  return (
+    Object.entries(map)
+      .map(
+        ([name, value]) => name + "=" + value.replaceAll("\n", String.raw`\n`),
+      )
+      .join("\n") + "\n"
+  );
+}
+
+export function validateKey(key) {
+  if (!KEY.test(key ?? "") || key.startsWith("sops_"))
+    throw new SecretError(
+      "KEY must be an environment variable name outside the reserved sops_ namespace",
+    );
+}
+
+export function validateMap(map) {
+  if (!map || typeof map !== "object" || Array.isArray(map))
+    throw new SecretError("sops returned an invalid secret map");
+  for (const [key, value] of Object.entries(map)) {
+    validateKey(key);
+    if (typeof value !== "string")
+      throw new SecretError("secret values must be strings");
+  }
+}

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

@@ -0,0 +1,20 @@
+// secret-errors.mjs - sanitized public errors shared by app secret operations.
+
+export class SecretError extends Error {}
+
+export const publicStorage = (action) => {
+  try {
+    return action();
+  } catch (error) {
+    throw new SecretError(
+      error.code ? `private storage failed (${error.code})` : error.message,
+    );
+  }
+};
+
+export function secretErrorMessage(error) {
+  if (error instanceof SecretError) return error.message;
+  if (error instanceof SyntaxError) return "invalid secret document";
+  const code = error.code ? ` (${error.code})` : "";
+  return `operation failed${code}; no secret values were printed`;
+}

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

@@ -0,0 +1,124 @@
+// secret-files.mjs — private files for app secrets, always outside the repository.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+/** The platform's SOPS age identity and StarCi local data roots. */
+export function secretRoots(env = process.env, platform = process.platform) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  const support = path.join(home, "Library", "Application Support");
+  let config;
+  if (platform === "win32")
+    config = env.APPDATA || path.join(home, "AppData", "Roaming");
+  else if (platform === "darwin") config = support;
+  else config = env.XDG_CONFIG_HOME || path.join(home, ".config");
+  let local;
+  if (platform === "win32")
+    local = env.LOCALAPPDATA || path.join(home, "AppData", "Local");
+  else if (platform === "darwin") local = support;
+  else local = env.XDG_DATA_HOME || path.join(home, ".local", "share");
+  return {
+    identity: path.resolve(config, "sops", "age", "keys.txt"),
+    local: path.resolve(local, "StarCi", "secrets"),
+  };
+}
+
+const inside = (root, target) => {
+  const relative = path.relative(root, target);
+  return (
+    relative === "" ||
+    (!relative.startsWith(`..${path.sep}`) &&
+      relative !== ".." &&
+      !path.isAbsolute(relative))
+  );
+};
+
+/** Reject repository custody, including a path spelled through a symlink or junction. */
+export function outsideRepository(repoRoot, target) {
+  const root = fs.realpathSync(repoRoot);
+  let ancestor = path.resolve(target);
+  while (!fs.existsSync(ancestor)) {
+    const parent = path.dirname(ancestor);
+    if (parent === ancestor)
+      throw new Error("cannot resolve the private storage root");
+    ancestor = parent;
+  }
+  const resolved = path.resolve(
+    fs.realpathSync(ancestor),
+    path.relative(ancestor, path.resolve(target)),
+  );
+  if (
+    inside(root, resolved) ||
+    inside(path.resolve(repoRoot), path.resolve(target))
+  )
+    throw new Error("private storage must be outside the repository");
+}
+
+/** Create private directories without following a symlink at any storage component. */
+export function privateDirectory(repoRoot, directory) {
+  outsideRepository(repoRoot, directory);
+  const missing = [];
+  for (let at = directory; !fs.existsSync(at); at = path.dirname(at))
+    missing.push(at);
+  for (const at of missing.reverse()) fs.mkdirSync(at, { mode: 0o700 });
+  for (let at = directory; ; at = path.dirname(at)) {
+    const stat = fs.lstatSync(at);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+      throw new Error("private storage must use ordinary directories");
+    if (path.dirname(at) === at) break;
+  }
+  outsideRepository(repoRoot, directory);
+  if (process.platform !== "win32") fs.chmodSync(directory, 0o700);
+}
+
+/** The declared project owns a separate environment directory on the local machine. */
+export function materializedDirectory(repoRoot, environment, env, platform) {
+  let project;
+  const declaration = path.join(repoRoot, "hfs.json");
+  if (fs.existsSync(declaration))
+    project = JSON.parse(fs.readFileSync(declaration, "utf8")).project;
+  if (!project && fs.existsSync(path.join(repoRoot, "package.json")))
+    project = JSON.parse(
+      fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"),
+    ).name;
+  project ||= path.basename(repoRoot);
+  if (
+    typeof project !== "string" ||
+    !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(project) ||
+    project === ".."
+  )
+    throw new Error("the project name must be a safe local directory name");
+  const directory = path.join(
+    secretRoots(env, platform).local,
+    project,
+    environment,
+  );
+  privateDirectory(repoRoot, directory);
+  return directory;
+}
+
+/** Atomically publish one KEY file; an existing link or hard link is never overwritten. */
+export function writeSecretFile(directory, key, value) {
+  const file = path.join(directory, key);
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1)
+      throw new Error("a private KEY file must be an ordinary file");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const temporary = path.join(directory, `.${key}-${randomUUID()}.tmp`);
+  try {
+    fs.writeFileSync(temporary, value, {
+      flag: "wx",
+      mode: 0o600,
+      flush: true,
+    });
+    fs.renameSync(temporary, file);
+    if (process.platform !== "win32") fs.chmodSync(file, 0o600);
+  } finally {
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+  }
+  return file;
+}

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

@@ -0,0 +1,192 @@
+// 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 { resolveSops } from "../api/sops/resolve-sops.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 {
+  outsideRepository,
+  privateDirectory,
+  secretRoots,
+} from "./secret-files.mjs";
+
+const PATH_RULE = String.raw`\.starcistacks[/\\][^/\\]+[/\\]secrets[/\\][^/\\]+\.enc$`;
+
+/** 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;
+}
+
+/** Reuse an existing matching age rule; initialization must not rotate an app's recipient. */
+export function initializeSecrets(repoRoot, { env, platform, tools, stdout }) {
+  const tool = secretTools(env, tools);
+  const configFile = path.join(repoRoot, ".sops.yaml");
+  const config = readInitializationConfig(configFile);
+  const rules = config.creation_rules ?? [];
+  const canonical = rules.find(
+    (rule) =>
+      rule?.path_regex === PATH_RULE &&
+      typeof rule.age === "string" &&
+      rule.age.trim(),
+  );
+  const existing =
+    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;
+      }
+    });
+  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 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",
+    );
+  let recipient;
+  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");
+    recipient = existing?.age ?? recipients.join(",");
+  } finally {
+    held.release();
+  }
+  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 the repo.\n${stringifyYaml(config)}`,
+  );
+  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,98 @@
+// 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 { 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 });
+
+/** 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 = { ...env };
+  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(env))
+    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(env).some((name) => /^SOPS_AGE_KEY(?:_FILE)?$/i.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: sopsInvocation },
+      );
+      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;
+    },
+    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: sopsInvocation },
+      );
+      if (result.status !== 0) throw refuse("seal the secret", result);
+      return result.stdout;
+    },
+  };
+}