@starci/hfs 4.2.17 → 4.4.0

package/runtime/scripts/hfs/secret-bootstrap-crypto.mjs

@@ -0,0 +1,200 @@
+import {
+  createCipheriv, createHash, createHmac, createPrivateKey, createPublicKey,
+  diffieHellman, hkdfSync, randomBytes,
+} from 'node:crypto';
+
+// Bootstrap only; interoperable with https://c2sp.org/age and getsops/sops.
+// See SOPS aes/cipher.go, sops.go, stores/dotenv/store.go, stores/flatten.go.
+const ALPHABET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+const GENERATORS = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+const PRIVATE_PREFIX = Buffer.from('302e020100300506032b656e04220420', 'hex');
+const PUBLIC_PREFIX = Buffer.from('302a300506032b656e032100', 'hex');
+
+function checksumStep(checksum, value) {
+  const top = checksum >>> 25;
+  let next = ((checksum & 0x1ffffff) << 5) ^ value;
+  for (let bit = 0; bit < 5; bit += 1) {
+    if ((top >>> bit) & 1) next ^= GENERATORS[bit];
+  }
+  return next >>> 0;
+}
+
+function checksumWords(prefix, words) {
+  const codes = [...prefix].map((character) => character.codePointAt(0));
+  const expanded = [...codes.map((code) => code >>> 5), 0, ...codes.map((code) => code & 31)];
+  return [...expanded, ...words].reduce(checksumStep, 1);
+}
+
+function convertBits(input, from, to, pad) {
+  let accumulator = 0;
+  let bits = 0;
+  const result = [];
+  const mask = (1 << to) - 1;
+  for (const value of input) {
+    accumulator = ((accumulator << from) | value) & 0xffff;
+    bits += from;
+    while (bits >= to) {
+      bits -= to;
+      result.push((accumulator >>> bits) & mask);
+    }
+  }
+  if (pad && bits) result.push((accumulator << (to - bits)) & mask);
+  if (!pad && (bits >= from || ((accumulator << (to - bits)) & mask))) {
+    throw new Error('Invalid age recipient encoding');
+  }
+  return result;
+}
+
+function bech32Encode(prefix, bytes) {
+  const words = convertBits(bytes, 8, 5, true);
+  const checksum = checksumWords(prefix, [...words, 0, 0, 0, 0, 0, 0]) ^ 1;
+  const suffix = [];
+  for (let index = 0; index < 6; index += 1) suffix.push((checksum >>> (5 * (5 - index))) & 31);
+  return prefix + '1' + [...words, ...suffix].map((word) => ALPHABET[word]).join('');
+}
+
+function decodeRecipient(recipient) {
+  if (typeof recipient !== 'string' || !recipient.startsWith('age1') || recipient.length !== 62) {
+    throw new Error('Bootstrap requires an X25519 age recipient');
+  }
+  const words = Array.from(recipient.slice(4), (character) => ALPHABET.indexOf(character));
+  if (words.includes(-1) || checksumWords('age', words) !== 1) {
+    throw new Error('Invalid age recipient checksum');
+  }
+  const decoded = Buffer.from(convertBits(words.slice(0, -6), 5, 8, false));
+  if (decoded.length !== 32) throw new Error('Invalid age recipient length');
+  return decoded;
+}
+
+function privateKey(bytes) {
+  const encoded = Buffer.concat([PRIVATE_PREFIX, bytes]);
+  try {
+    return createPrivateKey({ key: encoded, type: 'pkcs8', format: 'der' });
+  } finally {
+    encoded.fill(0);
+  }
+}
+
+function publicBytes(key) {
+  return createPublicKey(key).export({ type: 'spki', format: 'der' }).subarray(-32);
+}
+
+/** Return a fresh app identity in memory. The caller owns custody and zeroing. */
+export function generateAppIdentity() {
+  const seed = randomBytes(32);
+  try {
+    const recipient = bech32Encode('age', publicBytes(privateKey(seed)));
+    const identity = Buffer.from(bech32Encode('age-secret-key-', seed).toUpperCase());
+    return { identity, recipient };
+  } finally {
+    seed.fill(0);
+  }
+}
+
+function deriveKey(secret, salt, info) {
+  return Buffer.from(hkdfSync('sha256', secret, salt, info, 32));
+}
+
+function chachaSeal(plaintext, key, nonce) {
+  const cipher = createCipheriv('chacha20-poly1305', key, nonce, { authTagLength: 16 });
+  return Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+}
+
+function rawBase64(bytes) {
+  return bytes.toString('base64').replaceAll('=', '');
+}
+
+function wrapFileKey(fileKey, recipient) {
+  const seed = randomBytes(32);
+  const ephemeral = privateKey(seed);
+  seed.fill(0);
+  const share = publicBytes(ephemeral);
+  const peer = createPublicKey({ key: Buffer.concat([PUBLIC_PREFIX, recipient]), type: 'spki', format: 'der' });
+  const sharedSecret = diffieHellman({ privateKey: ephemeral, publicKey: peer });
+  const wrapKey = deriveKey(sharedSecret, Buffer.concat([share, recipient]), 'age-encryption.org/v1/X25519');
+  try {
+    const body = rawBase64(chachaSeal(fileKey, wrapKey, Buffer.alloc(12)));
+    return '-> X25519 ' + rawBase64(share) + '\n' + body + '\n';
+  } finally {
+    sharedSecret.fill(0);
+    wrapKey.fill(0);
+  }
+}
+
+function ageSealDataKey(dataKey, recipient) {
+  const fileKey = randomBytes(16);
+  const nonce = randomBytes(16);
+  const headerKey = deriveKey(fileKey, Buffer.alloc(0), 'header');
+  const payloadKey = deriveKey(fileKey, nonce, 'payload');
+  try {
+    const header = 'age-encryption.org/v1\n' + wrapFileKey(fileKey, recipient) + '---';
+    const mac = rawBase64(createHmac('sha256', headerKey).update(header).digest());
+    const chunkNonce = Buffer.alloc(12);
+    chunkNonce[11] = 1;
+    const ciphertext = chachaSeal(dataKey, payloadKey, chunkNonce);
+    return Buffer.concat([Buffer.from(header + ' ' + mac + '\n'), nonce, ciphertext]);
+  } finally {
+    fileKey.fill(0);
+    headerKey.fill(0);
+    payloadKey.fill(0);
+  }
+}
+
+function armor(bytes) {
+  const encoded = bytes.toString('base64');
+  const lines = [];
+  for (let offset = 0; offset < encoded.length; offset += 64) lines.push(encoded.slice(offset, offset + 64));
+  return ['-----BEGIN AGE ENCRYPTED FILE-----', ...lines, '-----END AGE ENCRYPTED FILE-----', ''].join('\n');
+}
+
+function sopsEncrypt(value, dataKey, additionalData) {
+  const iv = randomBytes(32);
+  const cipher = createCipheriv('aes-256-gcm', dataKey, iv);
+  cipher.setAAD(Buffer.from(additionalData));
+  const data = Buffer.concat([cipher.update(value, 'utf8'), cipher.final()]);
+  return 'ENC[AES256_GCM,data:' + data.toString('base64') + ',iv:' + iv.toString('base64')
+    + ',tag:' + cipher.getAuthTag().toString('base64') + ',type:str]';
+}
+
+function bootstrapEntries(values) {
+  if (!values || typeof values !== 'object' || Array.isArray(values)) {
+    throw new Error('Bootstrap values must be a dotenv key/value object');
+  }
+  const entries = Object.entries(values);
+  if (!entries.length) throw new Error('Bootstrap requires at least one value');
+  for (const [name, value] of entries) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || name.startsWith('sops_') || name.endsWith('_unencrypted')) {
+      throw new Error('Bootstrap contains an invalid or reserved dotenv key');
+    }
+    if (typeof value !== 'string' || !value.length) throw new Error('Bootstrap values must be nonempty strings');
+  }
+  return entries;
+}
+
+/** Encrypt bootstrap values to the app's public key; no private key is needed. */
+export function sealBootstrapValues({ values, recipient }) {
+  const entries = bootstrapEntries(values);
+  const recipientBytes = decodeRecipient(recipient);
+  const dataKey = randomBytes(32);
+  try {
+    const modified = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+    const digest = createHash('sha512');
+    const lines = entries.map(([name, value]) => {
+      digest.update(value, 'utf8');
+      return name + '=' + sopsEncrypt(value, dataKey, name + ':');
+    });
+    const mac = sopsEncrypt(digest.digest('hex').toUpperCase(), dataKey, modified);
+    const wrapped = armor(ageSealDataKey(dataKey, recipientBytes)).replaceAll('\n', String.raw`\n`);
+    lines.push(
+      'sops_age__list_0__map_enc=' + wrapped,
+      'sops_age__list_0__map_recipient=' + recipient,
+      'sops_lastmodified=' + modified,
+      'sops_mac=' + mac,
+      'sops_unencrypted_suffix=_unencrypted',
+      'sops_version=3.9.4',
+    );
+    return lines.join('\n') + '\n';
+  } finally {
+    dataKey.fill(0);
+  }
+}

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-edit.mjs

@@ -0,0 +1,170 @@
+// secret-edit.mjs - app secret unset|rename|remove: edit the key set of one sealed member without ever printing a value.
+// Each verb is a dry run until --execute. The dry run reads only the envelope's public key names and recipients, so it needs no
+// age identity. An executed edit decrypts the member in memory, re-seals it to the SAME recipients in the SAME sops format
+// (the one exception is a binary `data` envelope, which a rename re-seals as a JSON envelope), checks the sealed result and
+// publishes it atomically under the writer claim. Output names environments, members and keys only.
+import fs from "node:fs";
+import { isSopsEnvelope } from "../lib/sops-envelope.mjs";
+import { envelopeOf, plaintextOf, validateKey, validateMap } from "./secret-document.mjs";
+import { deleteSealed, fileOf, replaceSealed } from "./secret-store.mjs";
+import { SecretError } from "./secret-errors.mjs";
+
+const BINARY_PROPERTY = "data";
+const NOT_PRESERVED = /\r|\\n/u;
+
+const sameNames = (left, right) =>
+  left.length === right.length && left.every((name) => right.includes(name));
+
+/** True for the sops binary store: a JSON envelope whose only property is `data` (the ssh key and known_hosts members). */
+const isBinaryEnvelope = (envelope) =>
+  envelope.format === "json" &&
+  envelope.keys.length === 1 &&
+  envelope.keys[0] === BINARY_PROPERTY;
+
+function inspectMember(file, label) {
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch {
+    throw new SecretError(`${label} is not a sealed member of this environment`);
+  }
+  if (!stat.isFile() || stat.isSymbolicLink())
+    throw new SecretError(`${label} must be an ordinary sealed file`);
+  const text = fs.readFileSync(file, "utf8");
+  if (!isSopsEnvelope(text))
+    throw new SecretError(`${label} is not a sops envelope`);
+  return envelopeOf(text);
+}
+
+function requireKey(envelope, key, label) {
+  if (!envelope.keys.includes(key))
+    throw new SecretError(`${label} has no KEY ${key}`);
+}
+
+/** Decrypt the member in memory and check that it holds exactly the keys its envelope declares. */
+function openMap(file, envelope, sops) {
+  const map = sops.decrypt(file, envelope.format);
+  validateMap(map);
+  if (!sameNames(Object.keys(map), envelope.keys))
+    throw new SecretError("sops returned keys that differ from the envelope");
+  if (
+    envelope.format !== "dotenv" &&
+    Object.values(map).some((value) => NOT_PRESERVED.test(value))
+  )
+    throw new SecretError(
+      "a value holds a carriage return or literal backslash-n that this edit cannot preserve losslessly",
+    );
+  return map;
+}
+
+/** Seal the replacement map to the original recipients and prove the result before anything is published. */
+function sealReplacement({ file, format, map, envelope, sops }) {
+  const sealed = sops.seal({
+    inputType: format,
+    plaintext: plaintextOf(format, map),
+    recipients: envelope.recipients,
+    filenameOverride: file,
+  });
+  let parsed;
+  try {
+    parsed = envelopeOf(sealed);
+  } catch {
+    throw new SecretError("sops returned an invalid sealed document");
+  }
+  const recipientsKept =
+    !envelope.recipients.length ||
+    sameNames(parsed.recipients, envelope.recipients);
+  if (
+    !isSopsEnvelope(sealed) ||
+    parsed.format !== format ||
+    !sameNames(parsed.keys, Object.keys(map))
+  )
+    throw new SecretError("sops returned an invalid sealed document");
+  if (!recipientsKept)
+    throw new SecretError("sops returned a document sealed to different recipients");
+  return sealed;
+}
+
+const keyCount = (count) => `${count} key${count === 1 ? "" : "s"}`;
+
+function unsetKey({ file, label, key, execute, sops, stdout }) {
+  const envelope = inspectMember(file, label);
+  requireKey(envelope, key, label);
+  if (envelope.keys.length === 1)
+    throw new SecretError(
+      `${key} is the last KEY of ${label}; a sealed member cannot be empty, use remove ${label.replace("/", " ")} --force-nonempty to delete it`,
+    );
+  const remaining = envelope.keys.length - 1;
+  if (!execute) {
+    stdout(`dry run: would unset ${key} from ${label} (${keyCount(remaining)} remain); add --execute\n`);
+    return 0;
+  }
+  const seam = sops();
+  const map = openMap(file, envelope, seam);
+  delete map[key];
+  replaceSealed(file, sealReplacement({ file, format: envelope.format, map, envelope, sops: seam }));
+  stdout(`unset ${label} (${key}); ${keyCount(remaining)} remain\n`);
+  return 0;
+}
+
+/** The replacement map and format of a rename: the key keeps its position and value; a binary envelope becomes a JSON one. */
+function renamedMap({ file, envelope, from, to, sops }) {
+  if (isBinaryEnvelope(envelope)) {
+    const value = sops.decryptBinary(file);
+    if (typeof value !== "string" || value === "")
+      throw new SecretError("the binary envelope holds no content");
+    return { format: "json", map: { [to]: value } };
+  }
+  const map = openMap(file, envelope, sops);
+  const entries = Object.entries(map).map(([name, value]) => [name === from ? to : name, value]);
+  return { format: envelope.format, map: Object.fromEntries(entries) };
+}
+
+function renameKey({ file, label, key, to, execute, sops, stdout }) {
+  const envelope = inspectMember(file, label);
+  requireKey(envelope, key, label);
+  if (key === to) throw new SecretError("the new KEY equals the old KEY");
+  if (envelope.keys.includes(to))
+    throw new SecretError(`${label} already has KEY ${to}`);
+  const binary = isBinaryEnvelope(envelope);
+  if (!execute) {
+    const note = binary ? "; the binary envelope is re-sealed as a JSON envelope" : "";
+    stdout(`dry run: would rename ${key} to ${to} in ${label}${note}; add --execute\n`);
+    return 0;
+  }
+  const seam = sops();
+  const { format, map } = renamedMap({ file, envelope, from: key, to, sops: seam });
+  replaceSealed(file, sealReplacement({ file, format, map, envelope, sops: seam }));
+  stdout(`renamed ${key} to ${to} in ${label}${binary ? " (re-sealed as a JSON envelope)" : ""}\n`);
+  return 0;
+}
+
+function removeMember({ file, label, execute, force, stdout }) {
+  const envelope = inspectMember(file, label);
+  if (envelope.keys.length && !force)
+    throw new SecretError(
+      `${label} still holds ${keyCount(envelope.keys.length)} (${envelope.keys.join(", ")}); unset them first, or pass --force-nonempty to delete the whole member`,
+    );
+  if (!execute) {
+    stdout(`dry run: would remove ${label}.enc (${keyCount(envelope.keys.length)}); add --execute\n`);
+    return 0;
+  }
+  deleteSealed(file);
+  stdout(`removed ${label}.enc (${keyCount(envelope.keys.length)})\n`);
+  return 0;
+}
+
+/** Validate every name of an edit verb before anything touches the file system. */
+export function validateEditNames(verb, names) {
+  for (const name of names) validateKey(name);
+  if (verb === "remove" && names.length) throw new SecretError("remove takes no KEY");
+}
+
+/** unset, rename and remove; `sops` is a thunk so a dry run never needs the sops tool or an age identity. */
+export function editSecret(verb, { directory, environment, slug, names, execute, force, sops, stdout }) {
+  const file = fileOf(directory, slug);
+  const common = { file, label: `${environment}/${slug}`, execute, sops, stdout };
+  if (verb === "unset") return unsetKey({ ...common, key: names[0] });
+  if (verb === "rename") return renameKey({ ...common, key: names[0], to: names[1] });
+  return removeMember({ ...common, force });
+}

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