@starci/hfs 4.3.0 → 4.4.1

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

@@ -2,10 +2,15 @@
 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,
@@ -13,6 +18,68 @@ import {
 } 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) {
@@ -93,19 +160,14 @@ function readInitializationConfig(configFile) {
   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 ?? [];
+function existingInitializationRule(rules) {
   const canonical = rules.find(
     (rule) =>
       rule?.path_regex === PATH_RULE &&
       typeof rule.age === "string" &&
       rule.age.trim(),
   );
-  const existing =
+  return (
     canonical ??
     rules.find((rule) => {
       if (typeof rule?.age !== "string" || !rule.age.trim()) return false;
@@ -119,15 +181,11 @@ export function initializeSecrets(repoRoot, { env, platform, tools, stdout }) {
       } 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",
-    );
+    })
+  );
+}
+
+function legacyInitializationRecipient(repoRoot, env, platform, tool) {
   const identity = secretRoots(env, platform).identity;
   outsideRepository(repoRoot, identity);
   privateDirectory(repoRoot, path.dirname(identity));
@@ -136,7 +194,6 @@ export function initializeSecrets(repoRoot, { env, platform, tools, stdout }) {
     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], {
@@ -170,10 +227,55 @@ export function initializeSecrets(repoRoot, { env, platform, tools, stdout }) {
       recipients.some((value) => !/^age1[a-z0-9]+$/.test(value))
     )
       throw new Error("age-keygen returned an invalid public recipient");
-    recipient = existing?.age ?? recipients.join(",");
+    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.
@@ -181,8 +283,14 @@ export function initializeSecrets(repoRoot, { env, platform, tools, stdout }) {
   config.creation_rules = rules;
   fs.writeFileSync(
     configFile,
-    `# Initialized by starci app secret init; private age identities stay outside the repo.\n${stringifyYaml(config)}`,
+    `# 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(

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

@@ -6,11 +6,13 @@ 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 { 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(
@@ -20,7 +22,11 @@ export function defaultSops(
   tools,
 ) {
   const { sops: binary } = publicStorage(() => secretTools(env, tools));
-  const selectedEnv = { ...env };
+  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);
@@ -32,7 +38,7 @@ export function defaultSops(
           );
       }
     });
-  for (const [name, value] of Object.entries(env))
+  for (const [name, value] of Object.entries(selectedEnv))
     if (/^SOPS_AGE_KEY_FILE$/i.test(name) && value) {
       if (!path.isAbsolute(value))
         throw new SecretError(
@@ -41,7 +47,7 @@ export function defaultSops(
       checkIdentity(value);
     }
   if (
-    !Object.keys(env).some((name) => /^SOPS_AGE_KEY(?:_FILE)?$/i.test(name))
+    !Object.keys(selectedEnv).some((name) => AGE_IDENTITY_NAME.test(name))
   ) {
     const identity = secretRoots(env, platform).identity;
     checkIdentity(identity);
@@ -63,7 +69,7 @@ export function defaultSops(
       const result = sopsDecrypt(
         binary,
         ["decrypt", "--input-type", format, "--output-type", "dotenv", file],
-        { env: selectedEnv, cwd: repoRoot, invocation: sopsInvocation },
+        { env: selectedEnv, cwd: repoRoot, invocation },
       );
       if (result.status !== 0)
         throw refuse(
@@ -80,6 +86,32 @@ export function defaultSops(
       }
       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
@@ -89,7 +121,7 @@ export function defaultSops(
       const result = sopsSeal(
         binary,
         { ...request, recipients },
-        { env: selectedEnv, cwd: repoRoot, invocation: sopsInvocation },
+        { env: selectedEnv, cwd: repoRoot, invocation },
       );
       if (result.status !== 0) throw refuse("seal the secret", result);
       return result.stdout;