@starci/hfs 4.11.0 → 4.11.11

package/runtime/scripts/hfs/secret.mjs

@@ -1,25 +1,35 @@
 // secret.mjs - app secret init|set|get|unset|rename|remove|materialize|list|verify: sealed custody and private KEY files.
 // SOPS plaintext travels on stdin and stays in memory; normal CLI output contains names and local file paths only.
+// set seals one or more keys in one sops write: typed at a masked prompt on a terminal, KEY=value lines on redirected stdin
+// (the whole stdin for one key), or --generate (scripts/hfs/secret-prompt.mjs).
 // Every verb runs at the app root or --cwd. Exit 0 done, 2 refusal; --reveal is the only plaintext stdout path.
 // unset, rename and remove edit one sealed member and are dry runs until --execute (scripts/hfs/secret-edit.mjs).
 // verify decrypts each member in memory and names only keys and violated shapes, never a value (R249).
+// server-key makes the deploy server's own age identity on the server and seals the environment to it (stack/server-key.mjs).
 import fs from "node:fs";
 import path from "node:path";
 import { randomBytes } from "node:crypto";
 import { invocationDir } from "../lib/roots.mjs";
-import { initializeSecrets } from "./secret-init.mjs";
-import { validateKey } from "./secret-document.mjs";
+import { environmentRecipients, initializeSecrets, ownerRecipient } from "./secret-init.mjs";
+import { declareKeys, groupMap, migrateMember, printAudit, splitMember } from "./secret-standard.mjs";
+import { envelopeOf, validateKey } from "./secret-document.mjs";
 import { defaultSops } from "./secret-sops.mjs";
 import { fileOf, secretsDirectory, writeSecret } from "./secret-store.mjs";
 import { getSecret, listSecrets, materializeSecrets } from "./secret-output.mjs";
 import { SecretError, publicStorage, secretErrorMessage } from "./secret-errors.mjs";
 import { editSecret, validateEditNames } from "./secret-edit.mjs";
 import { verifySecrets } from "./rules/env-value-shape.mjs";
+import { setValues } from "./secret-prompt.mjs";
+import { stackContext } from "../../../stack/context.mjs";
+import { StackError } from "../../../stack/errors.mjs";
+import { serverKey } from "../../../stack/server-key.mjs";
 
 export { envelopeOf, formatOf, plaintextOf } from "./secret-document.mjs";
 export { setSecretValues } from "./secret-store.mjs";
 
-const VERBS = new Set(["init", "list", "get", "set", "unset", "rename", "remove", "materialize", "verify"]);
+const VERBS = new Set(["init", "list", "get", "set", "unset", "rename", "remove", "materialize", "verify", "recipients", "migrate", "split", "audit", "server-key"]);
+const MOVE_VERBS = new Set(["migrate", "split"]);
+const LIST_FLAGS = ["--add", "--remove", "--from-file", "--group"];
 const EDIT_VERBS = new Set(["unset", "rename", "remove"]);
 
 function valueOption(opts, flag, value) {
@@ -35,9 +45,13 @@ function parse(argv) {
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     const [flag, inline] = arg.split(/=(.*)/su);
-    if (["--cwd", "--generate"].includes(flag)) {
+    if (LIST_FLAGS.includes(flag)) {
+      const value = inline ?? argv[++i];
+      if (value === undefined || value.startsWith("--")) throw new SecretError(`${flag} needs a value`);
+      (opts[flag.slice(2)] ??= []).push(value);
+    } else if (["--cwd", "--generate", "--to", "--group-file", "--backup", "--restore"].includes(flag)) {
       valueOption(opts, flag, inline ?? argv[++i]);
-    } else if (["--to-file", "--reveal", "--execute", "--force-nonempty"].includes(flag)) {
+    } else if (["--to-file", "--reveal", "--execute", "--force-nonempty", "--into-existing", "--rotate"].includes(flag)) {
       if (inline !== undefined && !["true", "false"].includes(inline))
         throw new SecretError(`${flag} expects true or false`);
       opts[flag.slice(2)] = inline !== "false";
@@ -48,27 +62,31 @@ function parse(argv) {
   return opts;
 }
 
-const readStdin = () => {
-  if (process.stdin.isTTY)
-    throw new SecretError(
-      "set reads a value from redirected stdin; use --generate <bytes> to generate one",
-    );
-  return fs.readFileSync(0, "utf8");
-};
-
 function usageArguments(verb) {
   if (verb === "init") return "";
-  if (verb === "set") return "<env> <slug> <KEY> [--generate <bytes>]";
+  if (verb === "set") return "<env> <slug> <KEY> [KEY ...] [--generate <bytes>]";
   if (verb === "get") return "<env> <slug> [KEY] --to-file [--reveal]";
   if (verb === "unset") return "<env> <slug> <KEY> [--execute]";
   if (verb === "rename") return "<env> <slug> <OLD> <NEW> [--execute]";
   if (verb === "remove") return "<env> <slug> [--execute] [--force-nonempty]";
+  if (verb === "recipients") return "<env> [--add <age1...|owner>] [--remove <age1...|owner>]";
+  if (verb === "migrate") return "<env> <slug> [--to <slug>] [--into-existing] [--execute]";
+  if (verb === "split") return "<env> <slug> [--group KEY=member ...] [--group-file <yaml>] [--into-existing] [--execute]";
+  if (verb === "audit") return "[<env>]";
+  if (verb === "server-key") return "<env> [--rotate | --backup github | --restore github] [--execute]";
   return "<env>";
 }
 
 function editOptionsFor(verb, opts) {
-  if (opts.execute !== undefined && !EDIT_VERBS.has(verb))
-    throw new SecretError("--execute is only valid for unset, rename and remove");
+  if (opts.execute !== undefined && !EDIT_VERBS.has(verb) && !MOVE_VERBS.has(verb) && verb !== "server-key")
+    throw new SecretError("--execute is only valid for unset, rename, remove, migrate, split and server-key");
+  if ((opts.rotate !== undefined || opts.backup !== undefined || opts.restore !== undefined) && verb !== "server-key")
+    throw new SecretError("--rotate, --backup and --restore are only valid for server-key");
+  if (opts.to !== undefined && verb !== "migrate") throw new SecretError("--to is only valid for migrate");
+  if ((opts.group || opts["group-file"] !== undefined) && verb !== "split") throw new SecretError("--group and --group-file are only valid for split");
+  if (opts["into-existing"] !== undefined && !MOVE_VERBS.has(verb)) throw new SecretError("--into-existing is only valid for migrate and split");
+  if ((opts.add || opts.remove) && verb !== "recipients") throw new SecretError("--add and --remove are only valid for recipients");
+  if (opts["from-file"] && verb !== "set") throw new SecretError("--from-file is only valid for set");
   if (opts["force-nonempty"] !== undefined && verb !== "remove")
     throw new SecretError("--force-nonempty is only valid for remove");
 }
@@ -90,11 +108,16 @@ function optionsFor(verb, opts) {
     list: [1, 1],
     materialize: [1, 1],
     verify: [1, 1],
-    set: [3, 3],
+    set: [3, Infinity],
     get: [2, 3],
     unset: [3, 3],
     rename: [4, 4],
     remove: [2, 2],
+    recipients: [1, 1],
+    migrate: [2, 2],
+    split: [2, 2],
+    audit: [0, 1],
+    "server-key": [1, 1],
   }[verb];
   if (count < bounds[0] || count > bounds[1])
     throw new SecretError(
@@ -105,70 +128,136 @@ function optionsFor(verb, opts) {
   outputOptionsFor(verb, opts);
   editOptionsFor(verb, opts);
   if (EDIT_VERBS.has(verb)) validateEditNames(verb, opts.positional.slice(2));
-  if (verb === "set") validateKey(opts.positional[2]);
+  if (verb === "set") {
+    const keys = opts.positional.slice(2);
+    for (const key of keys) validateKey(key);
+    const twice = keys.find((key, index) => keys.indexOf(key) !== index);
+    if (twice) throw new SecretError(`set names ${twice} twice`);
+  }
   if (verb === "get" && opts.positional[2] !== undefined)
     validateKey(opts.positional[2]);
 }
 
-function secretValue(opts, stdin, random) {
-  let value;
-  if (opts.generate !== undefined) {
-    const bytes = Number(opts.generate);
-    if (!Number.isInteger(bytes) || bytes < 1 || bytes > 1024)
-      throw new SecretError(
-        "--generate must be a whole byte count from 1 to 1024",
-      );
-    value = random(bytes).toString("base64url");
-  } else {
-    if (typeof stdin !== "function" && stdin?.isTTY)
-      throw new SecretError("set requires redirected stdin");
-    value = String(
-      typeof stdin === "function"
-        ? stdin()
-        : fs.readFileSync(stdin?.fd ?? 0, "utf8"),
-    ).replace(/\r?\n$/u, "");
+/** The `--from-file KEY=path` values of set: each a named key, read byte for byte by setValues. */
+function fromFiles(entries, keys) {
+  const files = {};
+  for (const entry of entries ?? []) {
+    const at = entry.indexOf("=");
+    const key = entry.slice(0, at);
+    if (at < 1 || !entry.slice(at + 1)) throw new SecretError("--from-file takes KEY=path");
+    if (!keys.includes(key)) throw new SecretError(`--from-file names ${key}, which this set does not`);
+    if (Object.hasOwn(files, key)) throw new SecretError(`--from-file names ${key} twice`);
+    files[key] = entry.slice(at + 1);
   }
-  if (!value) throw new SecretError("the value on stdin is empty");
-  return value;
+  return files;
+}
+
+/** What `set` declared in the environment's stack `secrets:`, or the keys to declare by hand; nothing when all were declared. */
+function declarationLine(environment, { declared, byHand }) {
+  if (declared.length) return `declared ${declared.join(", ")} in environments.${environment}.secrets of application-stacks.yaml\n`;
+  if (byHand.length) return `declare ${byHand.join(", ")} in environments.${environment}.secrets of application-stacks.yaml (this environment's shape is wired by hand)\n`;
+  return "";
 }
 
-/** All app secrets verbs; stdin, sops, random and tool ports permit isolated custody specs. */
-export function secretMain(
+/** The app root of a sealed member: `<root>/.starcistacks/<env>/secrets/<slug>.enc`. */
+const appRootOf = (file) => path.resolve(path.dirname(file), "..", "..", "..");
+
+/**
+ * The success line of set: the member and its keys and, for a member this set created, the age identity a later set needs to
+ * open it (the recipient it is sealed to, and where this machine holds that identity, or the fix when it holds none). Names
+ * and paths only.
+ */
+function sealedLine(environment, slug, keys, file, created, seam) {
+  const head = `sealed ${environment}/${slug} (${keys.join(", ")})`;
+  if (!created) return `${head}\n`;
+  let recipients = [];
+  try { recipients = envelopeOf(fs.readFileSync(file, "utf8")).recipients; }
+  catch { recipients = []; }
+  const of = recipients.length ? ` of ${recipients.join(", ")}` : "";
+  let held = "";
+  if (seam.identity?.source) held = `; this machine holds it in ${seam.identity.source}`;
+  else if (seam.identity)
+    held = `; this machine holds none: add SOPS_AGE_KEY to ${path.join(appRootOf(file), ".claude", "secret.env")} before the next set`;
+  return `${head}; a new member: adding keys to it later needs the age identity${of}${held}\n`;
+}
+
+/** `server-key`: the deploy server's identity through the stack transport (`serverKeyIo`: { io, deps } of the specs), lines out. */
+async function serverKeyVerb(repoRoot, environment, opts, { env, stdout, stderr, open, serverKeyIo }) {
+  const ctx = stackContext({ cwd: repoRoot, env, stdout, stderr, openSops: open, ...serverKeyIo.io });
+  try {
+    const result = await serverKey(ctx, environment, {
+      execute: opts.execute === true, rotate: opts.rotate === true, backup: opts.backup, restore: opts.restore,
+    }, serverKeyIo.deps ?? {});
+    for (const line of result.lines) stdout(`${line}\n`);
+    return result.ok ? 0 : 1;
+  } catch (error) {
+    if (!(error instanceof StackError)) throw error;
+    stderr(`starci app secret: ${error.message}\n`);
+    return error.exit;
+  }
+}
+
+/**
+ * All app secrets verbs; stdin, prompt, sops, random and tool ports permit isolated custody specs. `hostIdentity`
+ * (`{ label, read }`) is the harness CLI's secret.env SOPS_AGE_KEY, the last place before keys.txt the age identity is looked for.
+ */
+export async function secretMain(
   argv,
   {
     stdout = (s) => process.stdout.write(s),
     stderr = (s) => process.stderr.write(s),
-    stdin = readStdin,
+    stdin,
+    prompt,
+    hostIdentity = null,
     sops = null,
     random = randomBytes,
     env = process.env,
     cwd = invocationDir(),
     platform = process.platform,
     tools,
+    serverKeyIo = {},
   } = {},
 ) {
   const [verb, ...rest] = argv;
   try {
     if (!VERBS.has(verb))
       throw new SecretError(
-        "usage: starci app secret init | set <env> <slug> <KEY> | get <env> <slug> [KEY] --to-file | unset <env> <slug> <KEY> | rename <env> <slug> <OLD> <NEW> | remove <env> <slug> | materialize <env> | list <env> | verify <env>",
+        "usage: starci app secret init | set <env> <slug> <KEY> [KEY ...] | get <env> <slug> [KEY] --to-file | unset <env> <slug> <KEY> | rename <env> <slug> <OLD> <NEW> | remove <env> <slug> | materialize <env> | list <env> | verify <env> | recipients <env> | migrate <env> <slug> [--to <slug>] [--into-existing] | split <env> <slug> [--group KEY=member] [--group-file <yaml>] [--into-existing] | audit [<env>] | server-key <env> [--rotate | --backup github | --restore github] [--execute]",
       );
     const opts = parse(rest);
     optionsFor(verb, opts);
     const repoRoot = path.resolve(cwd, opts.cwd ?? ".");
     if (verb === "init")
       return publicStorage(() =>
-        initializeSecrets(repoRoot, { env, platform, tools, stdout }),
+        initializeSecrets(repoRoot, { env, platform, tools, stdout, host: hostIdentity }),
+      );
+    if (verb === "audit") return printAudit(repoRoot, opts.positional[0] ?? null, stdout);
+    if (verb === "recipients")
+      return publicStorage(() =>
+        environmentRecipients(repoRoot, opts.positional[0], {
+          add: opts.add ?? [], remove: opts.remove ?? [], stdout,
+          owner: () => ownerRecipient(repoRoot, env, { platform, tools, host: hostIdentity }),
+        }),
       );
     const [environment, slug, key] = opts.positional;
+    if (verb === "server-key")
+      return await serverKeyVerb(repoRoot, environment, opts, {
+        env, stdout, stderr, serverKeyIo,
+        open: () => sops ?? defaultSops(env, repoRoot, platform, tools, hostIdentity),
+      });
     const directory = secretsDirectory(repoRoot, environment);
     if (verb === "list") return listSecrets(directory, stdout);
-    const open = () => sops ?? defaultSops(env, repoRoot, platform, tools);
+    const open = () => sops ?? defaultSops(env, repoRoot, platform, tools, hostIdentity);
     if (EDIT_VERBS.has(verb))
       return editSecret(verb, {
         directory, environment, slug, names: opts.positional.slice(2),
         execute: opts.execute === true, force: opts["force-nonempty"] === true, sops: open, stdout,
       });
+    if (MOVE_VERBS.has(verb)) {
+      const move = { directory, environment, member: slug, to: opts.to, intoExisting: opts["into-existing"] === true, execute: opts.execute === true, sops: open, stdout };
+      if (verb === "migrate") return migrateMember(move);
+      return splitMember({ ...move, groups: groupMap(opts.group, opts["group-file"] === undefined ? null : path.resolve(cwd, opts["group-file"])) });
+    }
     const seam = open();
     if (verb === "verify")
       return verifySecrets({ repoRoot, directory, environment, sops: seam, stdout });
@@ -177,9 +266,14 @@ export function secretMain(
       return materializeSecrets(directory, seam, output);
     const file = fileOf(directory, slug);
     if (verb === "get") return getSecret(file, key, seam, opts, output, stderr);
-    const value = secretValue(opts, stdin, random);
-    writeSecret({ file, values: { [key]: value }, age: [], sops: seam });
-    stdout(`sealed ${environment}/${slug} (${key})\n`);
+    const keys = opts.positional.slice(2);
+    const created = !fs.existsSync(file);
+    // Adding a key decrypts the member, so its identity is checked before any value is asked for; replacing every key does not.
+    if (!created && !envelopeOf(fs.readFileSync(file, "utf8")).keys.every((name) => keys.includes(name))) seam.requireIdentity?.(file);
+    const values = await setValues(keys, { generate: opts.generate, stdin, prompt, random, fromFile: fromFiles(opts["from-file"], keys) });
+    writeSecret({ file, values, age: [], sops: seam });
+    stdout(sealedLine(environment, slug, keys, file, created, seam));
+    stdout(declarationLine(environment, declareKeys(repoRoot, environment, slug, keys)));
     return 0;
   } catch (error) {
     const message = secretErrorMessage(error);

package/runtime/scripts/hfs/slots.mjs

@@ -127,6 +127,13 @@ function sideDeclaration(manifest, declaration, name, edition, providers) {
   });
 }
 
+/** R334: an app's bare database function name must be a pg built-in the canon lists bare (ruleParams.be.dbFunctions); any other is schema.name. */
+function bareDbFunctionProblems(manifest, be) {
+  const builtins = new Set((manifest.ruleParams?.be?.dbFunctions ?? []).map((entry) => entry.name).filter((name) => !name.includes('.')));
+  return (be?.dbFunctions ?? []).filter((entry) => !entry.name.includes('.') && !builtins.has(entry.name))
+    .map((entry) => `sides.be.dbFunctions names ${entry.name} bare, but a bare name is only a pg built-in of the canon's list (ruleParams.be.dbFunctions); name a function of a migration schema-qualified (public.${entry.name})`);
+}
+
 /**
  * A declaration checked against the manifest: kind app, the pinned major the manifest's (HFS_MANIFEST_MAJOR_MISMATCH otherwise,
  * and there is no compatibility window), and per side: app kinds of that profile, optionalSlots naming only opt-in slots of the
@@ -142,7 +149,7 @@ export function resolveRepoDeclaration(manifest, declaration, { file = HFS_DECLA
   if (declaration.kind === RUNTIME_KIND) return runtimeDeclaration(manifest, declaration, file, side);
   const { edition, known, valid } = declarationEdition(manifest, declaration);
   if (!valid) fail('HFS_EDITION_INVALID', `hfs.json edition is ${JSON.stringify(declaration.edition)}; the editions this manifest knows are ${known.join(', ')} (absent means full)`, { file, edition: declaration.edition });
-  const bad = PROFILES.flatMap((name) => sideProblems(manifest, name, declaration.sides[name], edition));
+  const bad = [...PROFILES.flatMap((name) => sideProblems(manifest, name, declaration.sides[name], edition)), ...bareDbFunctionProblems(manifest, declaration.sides.be)];
   if (bad.length) declarationInvalid(bad, file);
   if (side !== null && !PROFILES.includes(side)) fail('HFS_DECLARATION_INVALID', `${side} is not a side of an app (be, fe)`, { file, side });
   // A provider declared on any connection enables the provider slots of every profile (a fe side declares none): each view carries the union.

package/runtime/scripts/hfs/stack-deploy-config.mjs

@@ -13,6 +13,7 @@ export const KEY = /^[A-Z][A-Z0-9_]*$/u;
 const VOLUME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/u;
 const HOST_ALIAS = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
 const REMOTE_BASE = /^\/[A-Za-z0-9._/-]+$/u;
+const AGE_RECIPIENT = /^age1[a-z0-9]+$/u;
 const HTTP_URL = /^https?:\/\/[^\s]+$/u;
 const PINNED_HELPER_IMAGE = /^[a-z0-9./_-]+(?::[A-Za-z0-9._-]+)?@sha256:(?!0{64}$)[0-9a-f]{64}$/u;
 const ARGUMENT = /^[A-Za-z0-9_@%+=:,./-]+$/u;
@@ -20,7 +21,7 @@ const UPPER_ENV = KEY;
 
 const FIELDS = {
   deploy: ['stack', 'remote', 'images', 'volumes', 'secrets', 'environment', 'configs', 'passEnv', 'postDeploy', 'verify', 'jobs', 'tasks', 'backup', 'ingress', 'registry'],
-  remote: ['host', 'releasesBase', 'sealed'],
+  remote: ['host', 'releasesBase', 'sealed', 'serverRecipient'],
   sealed: ['ops', 'sshKey', 'knownHosts'],
   image: ['app', 'buildArgs'],
   buildArgs: ['values', 'sealed'],
@@ -51,9 +52,15 @@ function stringList(c, at, value, itemPattern, { nonEmpty = false } = {}) {
   return value;
 }
 
+/**
+ * `deploy.remote`: the ssh alias, the releases root, the sealed owner-machine session and `serverRecipient`, the public age
+ * recipient of the server's own identity that `starci app secret server-key` records.
+ */
 function remote(c, block) {
-  if (block === undefined) return { host: 'vps', releasesBase: null, sealed: null };
-  if (!closedFields(c, 'deploy.remote', block, FIELDS.remote)) return { host: 'vps', releasesBase: null, sealed: null };
+  const fallback = { host: 'vps', releasesBase: null, sealed: null, serverRecipient: null };
+  if (block === undefined) return fallback;
+  if (!closedFields(c, 'deploy.remote', block, FIELDS.remote)) return fallback;
+  if (block.serverRecipient !== undefined) patternField(c, 'deploy.remote.serverRecipient', block.serverRecipient, AGE_RECIPIENT);
   if (block.host !== undefined) nameField(c, 'deploy.remote.host', block.host, HOST_ALIAS);
   if (block.releasesBase !== undefined && (!REMOTE_BASE.test(String(block.releasesBase)) || String(block.releasesBase).includes('..')))
     c.problem('deploy.remote.releasesBase', 'must be an absolute path without ..');
@@ -62,7 +69,7 @@ function remote(c, block) {
     for (const key of FIELDS.sealed) nameField(c, `deploy.remote.sealed.${key}`, block.sealed[key]);
     sealed = { ...block.sealed };
   }
-  return { host: block.host ?? 'vps', releasesBase: block.releasesBase ?? null, sealed };
+  return { host: block.host ?? 'vps', releasesBase: block.releasesBase ?? null, sealed, serverRecipient: block.serverRecipient ?? null };
 }
 
 function imageBuildArgs(c, at, block, members) {
@@ -124,16 +131,30 @@ function grants(c, block, services, members) {
   return out;
 }
 
+/**
+ * `deploy.secrets.settings`: one `{ member, keys }` or a list of them, one per member whose plain one-line values the stack
+ * interpolates; a key named by two entries is refused, so every setting has one source.
+ */
 function secretSettings(c, block, members) {
-  if (block === undefined) return null;
-  if (!closedFields(c, 'deploy.secrets.settings', block, FIELDS.settings)) return null;
-  memberRef(c, 'deploy.secrets.settings.member', block.member, members);
-  return { member: block.member, keys: stringList(c, 'deploy.secrets.settings.keys', block.keys, KEY, { nonEmpty: true }) };
+  if (block === undefined) return [];
+  const entries = Array.isArray(block) ? block : [block];
+  const seen = new Set();
+  return entries.flatMap((entry, index) => {
+    const at = Array.isArray(block) ? `deploy.secrets.settings[${index}]` : 'deploy.secrets.settings';
+    if (!closedFields(c, at, entry, FIELDS.settings)) return [];
+    memberRef(c, `${at}.member`, entry.member, members);
+    const keys = stringList(c, `${at}.keys`, entry.keys, KEY, { nonEmpty: true });
+    for (const key of keys) {
+      if (seen.has(key)) c.problem(`${at}.keys`, `${key} is named by another settings entry`);
+      seen.add(key);
+    }
+    return [{ member: entry.member, keys }];
+  });
 }
 
 function secrets(c, block, services, members) {
-  if (block === undefined) return { grants: [], settings: null };
-  if (!closedFields(c, 'deploy.secrets', block, FIELDS.secrets)) return { grants: [], settings: null };
+  if (block === undefined) return { grants: [], settings: [] };
+  if (!closedFields(c, 'deploy.secrets', block, FIELDS.secrets)) return { grants: [], settings: [] };
   if (block.grants !== undefined && !Array.isArray(block.grants)) c.problem('deploy.secrets.grants', 'must be a list');
   return { grants: grants(c, block.grants, services, members), settings: secretSettings(c, block.settings, members) };
 }

package/runtime/scripts/hfs/stacks-gate.mjs

@@ -6,6 +6,7 @@ import {parseYaml} from '../../engine/yaml.mjs';
 import { validateAgainstSchema } from '../lib/json-schema.mjs';
 import { PROVISION_OPERATION_SCHEMA_REF, provisionOperationSchema } from '../lib/provision-operation-schema.mjs';
 import {slash} from '../lib/path-key.mjs';
+import { envelopeOf } from './secret-document.mjs';
 import { isInside, walkFiles } from '../lib/walk.mjs';
 import { composeIncludePaths, swarmInventoryIssues, swarmModelIssues } from '../lib/swarm-stack.mjs';
 import { swarmHardeningIssues } from './rules/stacks-swarm.mjs';
@@ -204,6 +205,7 @@ const checkStackEntry=(entry,environmentNames,add,{stacksRoot,lite})=>{
   if(!entry.isDirectory()||entry.isSymbolicLink())return;
   if(entry.name==='tmp'){add('STACKS_SCRATCH_IN_CANONICAL',`${STACKS_DIR}/tmp`,'scratch belongs in the OS temp directory, not a tracked .starcistacks/tmp');return;}
   if(entry.name==='k8s')return;
+  if(lite&&entry.name==='images')return; // the managed db image (slot app.db.image, ruling lite-db-image-in-stacks), no environment
   if(lite&&liteCustodyDirectory(path.join(stacksRoot,entry.name)))return;
   if(!environmentNames.has(entry.name))add('STACKS_UNDECLARED_ENVIRONMENT',`${STACKS_DIR}/${entry.name}`,`${entry.name} is not an environment the declaration admits; either the declaration admits it or it is not an environment`);
 };
@@ -254,9 +256,14 @@ const checkSecret=(secret,at,{envDir,environment,root,tracked,secretNames,add})=
   if(!object(secret))return;
   if(secretNames.has(secret.name))add('secret-duplicate',`${at}.name`,'secret names must be unique');else secretNames.add(secret.name);
   const plain=nonempty(secret.where)?resolvedPath(envDir,secret.where):null;
-  const enc=nonempty(secret.where)?resolvedPath(envDir,`${secret.where}.enc`):null;
+  // The member of `where` is `<where>.enc.yaml`, or a legacy `<where>.enc` (scripts/lib/sealed-member.mjs); an entry naming `key`
+  // declares that one key of the member, which its envelope must hold.
+  const member=nonempty(secret.where)?[`${secret.where}.enc.yaml`,`${secret.where}.enc`].map(name=>resolvedPath(envDir,name)).find(file=>file&&regular(file,{root:envDir})):null;
+  const enc=member??(nonempty(secret.where)?resolvedPath(envDir,`${secret.where}.enc.yaml`):null);
   if(!enc||!regular(enc,{root:envDir})||!sopsEnvelope(enc))
-    add('encrypted-ref-invalid',`${at}.where`,'secret must resolve to <where>.enc as a recognizable SOPS envelope, an existing regular file below the environment directory');
+    add('encrypted-ref-invalid',`${at}.where`,'secret must resolve to <where>.enc.yaml (or a legacy <where>.enc) as a recognizable SOPS envelope, an existing regular file below the environment directory');
+  else if(nonempty(secret.key)&&!envelopeOf(fs.readFileSync(enc,'utf8')).keys.includes(secret.key))
+    add('encrypted-ref-invalid',`${at}.key`,`the member at ${secret.where} holds no ${secret.key}`);
   if(nonempty(secret.where)&&!plain)
     add('materialized-path-invalid',`${at}.where`,'secret plaintext path and its existing ancestors must remain below the environment directory without symlinks');
   if(!String(secret.recipientPolicy??'').trim()||!String(secret.keyCustody??'').trim())

package/runtime/scripts/hfs/starcistacks-runtime.mjs

@@ -56,6 +56,6 @@ export function liteCustodyDirectory(directory) {
     if (entry.isFile()) return entry.name === 'environment.json';
     if (!entry.isDirectory() || entry.name !== 'secrets') return false;
     return fs.readdirSync(path.join(directory, entry.name), { withFileTypes: true })
-      .every(secret => secret.isFile() && !secret.isSymbolicLink() && (secret.name === '.gitkeep' || /^[a-z0-9-]+\.enc$/.test(secret.name)));
+      .every(secret => secret.isFile() && !secret.isSymbolicLink() && (secret.name === '.gitkeep' || /^[a-z0-9-]+\.enc(?:\.yaml)?$/.test(secret.name)));
   });
 }

package/runtime/scripts/lib/sealed-member.mjs

@@ -0,0 +1,36 @@
+// sealed-member.mjs - the file names of an app's sealed members (ruling app-secrets-one-standard): a member is
+// `.starcistacks/<env>/secrets/<member>.enc.yaml`, a sops YAML document of one provider's keys; a legacy member is
+// `<member>.enc`, a sops dotenv document, read until `starci app secret migrate` moves it. Every reader of the secrets
+// folder names, lists and resolves members through this module.
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** The suffix of a member, and of a legacy one. */
+export const MEMBER_SUFFIX = '.enc.yaml';
+export const LEGACY_SUFFIX = '.enc';
+
+/** A sealed member's file name (either suffix), as a pattern for a name or the tail of a path. */
+export const SEALED_NAME = /\.enc(?:\.yaml)?$/u;
+
+/** True for the file name of a sealed member, current or legacy. */
+export const isSealedName = (name) => SEALED_NAME.test(name);
+
+/** True for the file name of a legacy (dotenv `.enc`) member. */
+export const isLegacyName = (name) => name.endsWith(LEGACY_SUFFIX);
+
+/** The member a sealed file name holds (`sepay.enc.yaml` and `sepay.enc` are both `sepay`). */
+export const memberOfName = (name) => name.replace(SEALED_NAME, '');
+
+/**
+ * The file of member `slug` in `directory`: the existing `.enc.yaml`, else the existing legacy `.enc`, else the `.enc.yaml` a new
+ * member is created as. Both present is refused: one member has one file.
+ */
+export function memberFile(directory, slug) {
+  const current = path.join(directory, `${slug}${MEMBER_SUFFIX}`);
+  const legacy = path.join(directory, `${slug}${LEGACY_SUFFIX}`);
+  const hasCurrent = fs.existsSync(current);
+  if (hasCurrent && fs.existsSync(legacy))
+    throw new Error(`${slug} is sealed twice (${slug}${MEMBER_SUFFIX} and ${slug}${LEGACY_SUFFIX}); remove the one migrate replaced`);
+  if (hasCurrent) return current;
+  return fs.existsSync(legacy) ? legacy : current;
+}

package/runtime/scripts/lib/secret-patterns.mjs

@@ -11,7 +11,7 @@ export const FORBIDDEN_FILES = [
   { name: 'private-key-file', test: (f) => /\.(pem|key|p12|pfx)$/i.test(f) || /(^|\/)id_(rsa|ed25519|ecdsa)$/i.test(f) },
   // .starcistacks/<stack>/secrets/ commits sops twins only (owner ruling push-scan-test-secrets-encrypted): a plaintext
   // credential there - a test password included - is git-ignored by the product repo and never pushed.
-  { name: 'starcistacks-secret-plaintext', test: (f) => /(^|\/)\.starcistacks\/[^/]+\/secrets\//i.test(f) && !/(\.enc|\/\.gitkeep|\/KEYS\.md)$/i.test(f) },
+  { name: 'starcistacks-secret-plaintext', test: (f) => /(^|\/)\.starcistacks\/[^/]+\/secrets\//i.test(f) && !/(\.enc|\.enc\.yaml|\/\.gitkeep|\/KEYS\.md)$/i.test(f) },
   { name: 'credentials-json', test: (f) => /(^|\/)(credentials|service-account|client_secret)[^/]*\.json$/i.test(f) },
 ];
 // `word` in any case (name checks are case-aware by construction, not by flag).

package/runtime/scripts/lib/swarm-stack.mjs

@@ -51,7 +51,7 @@ export function swarmInventoryIssues({ components, lite = false }) {
   for (const [id, entry] of Object.entries(catalog)) {
     const component = mapping(entry);
     if (lite && present(component.image) && BACKING_IMAGE.test(repositoryOf(component.image)))
-      add(`components.${id}.image`, 'lite runs no backing image; its db component runs the image db/Dockerfile builds, storage is the external S3 endpoint, identity the API');
+      add(`components.${id}.image`, 'lite runs no backing image; its db component runs the image .starcistacks/images/db/Dockerfile builds, storage is the external S3 endpoint, identity the API');
     jobDeclarationIssues(id, component, catalog, add);
   }
   return errors;
@@ -119,7 +119,7 @@ export function swarmModelIssues({ model, components, bindings, lite = false })
     else if (service.ports?.length && component.role !== 'ingress')
       add(`services.${id}.ports`, 'only a component with role ingress may publish Swarm ports');
     if (lite && present(service.image) && BACKING_IMAGE.test(repositoryOf(service.image)))
-      add(`services.${id}.image`, 'lite stack runs no backing image; its db service runs the image db/Dockerfile builds');
+      add(`services.${id}.image`, 'lite stack runs no backing image; its db service runs the image .starcistacks/images/db/Dockerfile builds');
     jobServiceIssues(id, service, component, services, bound, add);
   }
   for (const id of Object.keys(bound)) {

package/scaffold/add-inbox-lite.mjs

@@ -102,7 +102,7 @@ const databasePatches = (root) => {
   ];
 };
 
-/** The first webhook installs only the lite inbox claim and transactional event publisher, shared by all providers. */
+/** The first webhook installs only the lite inbox claim and the pgmq event bus, shared by all providers. */
 const handoffPlatformFiles = (root, values) => {
   const planned = [];
   for (const capability of ["inbox", "idempotency", "event-bus"]) {
@@ -229,7 +229,7 @@ export function addLiteWebhookInbox({
     ...handoffPlatformFiles(root, renderValues),
   ];
   const hasHandoffStorage = migrations.some((file) =>
-    /create\s+table\s+public\.event_bus\b/i.test(fs.readFileSync(path.join(migrationsDir, file), "utf8")),
+    /create\s+function\s+public\.event_bus_send\b/i.test(fs.readFileSync(path.join(migrationsDir, file), "utf8")),
   );
   if (!hasHandoffStorage)
     planned[0].text = `${template("platform/migration.sql.tpl", renderValues)}\n${template("platform/client-operation-outcomes.sql.tpl", renderValues)}\n${planned[0].text}`;

package/scaffold/app.mjs

@@ -145,7 +145,7 @@ const STARTER_DEPENDENCIES = Object.freeze({
   dependencies: {
     '@apollo/server': null, '@nestjs/apollo': null, '@nestjs/common': null, '@nestjs/core': null, '@nestjs/cqrs': null, '@nestjs/graphql': null,
     '@nestjs/platform-express': null, '@nestjs/typeorm': null, 'nest-commander': null, pg: null, graphql: null,
-    'class-transformer': null, 'class-validator': null, 'reflect-metadata': null, rxjs: null, tslib: null, typeorm: null, zod: null,
+    'class-transformer': null, 'class-validator': null, 'reflect-metadata': null, rxjs: null, tslib: null, typeorm: null, undici: null, zod: null,
   },
   devDependencies: {
     turbo: null, '@nestjs/testing': null, '@starci/eslint-canon-be': null, '@starci/eslint-canon-fe': null, '@starci/jest-preset': null,
@@ -167,7 +167,7 @@ const LITE_STARTER_DEPENDENCIES = Object.freeze({
     '@nestjs/platform-express': null, '@nestjs/typeorm': null, '@nestjs/passport': null, passport: null, 'passport-google-oauth20': null, 'passport-local': null,
     '@aws-sdk/client-s3': null, '@aws-sdk/s3-request-presigner': null, bcryptjs: null,
     'class-transformer': null, 'class-validator': null, graphql: null, jose: null, pg: null,
-    'reflect-metadata': null, rxjs: null, tslib: null, typeorm: null, zod: null,
+    'reflect-metadata': null, rxjs: null, tslib: null, typeorm: null, undici: null, zod: null,
   },
   devDependencies: {
     turbo: null, '@nestjs/testing': null, '@starci/eslint-canon-be': null, '@starci/eslint-canon-fe': null,

package/src/main.mjs

@@ -108,7 +108,7 @@ starci app codemod button-intent [--write] [--format json|markdown] [--report <f
 starci app sync (--check | --write) [--cwd <dir>]
 starci app check [--cwd <dir>] [--json] [--fast] [--base <ref>] [--wiring] [--coverage-from <lcov>]
 starci app db new <kebab-name> [--json] [--cwd <dir>]
-starci app db baseline [--stamp <version>] [--url-env <NAME>] [--apply] [--cwd <dir>]
+starci app db baseline [--stamp <version>] [--url-env <NAME>] [--squash [--drop-extension <a,b>] [--drop-pgmq-queue <q,job_*>] [--seed-tables <t1,t2>] [--image <ref>]] [--apply] [--cwd <dir>]
 starci app db restamp --map <restamp.yaml> [--url-env <NAME>] [--apply] [--cwd <dir>]
 starci app db plan [--url-env <NAME>] [--json] [--cwd <dir>]
 starci app db dump [--url-env <NAME>] --out <dir> [--schema-only] [--json] [--cwd <dir>]
@@ -135,6 +135,7 @@ starci app secret remove <env> <slug> [--execute] [--force-nonempty] [--cwd <dir
 starci app secret materialize <env> [--cwd <dir>]
 starci app secret list <env> [--cwd <dir>]
 starci app secret verify <env> [--cwd <dir>]
+starci app secret server-key <env> [--rotate | --backup github | --restore github] [--execute] [--cwd <dir>]
 starci app ci secret set <NAME> [--env E | --dependabot] [--repo owner/name] [--cwd <dir>]
 starci app ci var set <NAME> [--env E] [--value v] [--repo owner/name] [--cwd <dir>]
 starci app ci var sync [--execute] [--repo owner/name] [--cwd <dir>]
@@ -460,11 +461,12 @@ function errorMessage(error) {
 /**
  * `harness` ({ version }) is the CLI that runs this package in-process: its version is the starci-harness an app is judged and
  * scaffolded at (runtime/scripts/hfs/canon-pins.mjs). `run` injects the database runner, `runLinter` the linter transport, `checkApp`
- * the HFS check and `stackIo` Swarm tools; production defaults execute every check.
+ * the HFS check and `stackIo` Swarm tools; production defaults execute every check. `hostIdentity` ({ label, read }) is the
+ * harness CLI's own secret.env SOPS_AGE_KEY, which `secret` reads last for the age identity; `prompt` replaces its masked prompt.
  */
 export async function main(argv, {
   cwd: baseCwd = process.cwd(), harness, stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier, lock, run, stackMain,
-  env = process.env, stdin, sops, tools, platform, stackIo, runLinter, checkApp,
+  env = process.env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runLinter, checkApp,
 } = {}) {
   try {
     const global = globalOptions(argv, path.resolve(baseCwd));
@@ -472,7 +474,7 @@ export async function main(argv, {
     const out = global.quiet ? () => {} : stdout;
     if (global.help) { out(USAGE); return 0; }
     if (!VERBS.includes(verb)) { stderr(USAGE); return 2; }
-    return await dispatchMain(verb, rest, { cwd: global.cwd, harness, edition: global.edition, stdout: out, stderr, presets, prettier, lock, run, stackMain, env, stdin, sops, tools, platform, stackIo, runLinter, checkApp });
+    return await dispatchMain(verb, rest, { cwd: global.cwd, harness, edition: global.edition, stdout: out, stderr, presets, prettier, lock, run, stackMain, env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runLinter, checkApp });
   } catch (error) {
     stderr(errorMessage(error));
     return 2;

package/stack/age-install.mjs

@@ -6,7 +6,8 @@ const AGE_VERSION = 'v1.2.1';
 const AGE_URL = `https://github.com/FiloSottile/age/releases/download/${AGE_VERSION}/age-${AGE_VERSION}-linux-amd64.tar.gz`;
 /** sha256 of the official linux/amd64 archive of AGE_VERSION. */
 const AGE_SHA256 = '7df45a6cc87d4da11cc03a539a7470c15b1041ab2b396af088fe9990f7c79d50';
-const INSTALL = { dnf: 'sudo -n dnf install -y age', yum: 'sudo -n yum install -y age', apk: 'sudo -n apk add age', 'apt-get': 'sudo -n apt-get install -y age' };
+/** The install command of each package manager installAge detects; a refusal names them for a host it cannot install on. */
+export const AGE_INSTALL = { dnf: 'sudo -n dnf install -y age', yum: 'sudo -n yum install -y age', apk: 'sudo -n apk add age', 'apt-get': 'sudo -n apt-get install -y age' };
 
 const STATIC_INSTALL = [
   'set -e',
@@ -26,8 +27,8 @@ export function installAge(run, report) {
   if (present(run)) return;
   const manager = packageManager(run);
   let failure = 'no package manager (dnf, yum, apk, apt-get) found';
-  if (Object.hasOwn(INSTALL, manager)) {
-    const packaged = run(INSTALL[manager]);
+  if (Object.hasOwn(AGE_INSTALL, manager)) {
+    const packaged = run(AGE_INSTALL[manager]);
     if (packaged.status === 0 && present(run)) { report.note(`installed age with ${manager}`); return; }
     failure = `${manager} could not install age: ${firstLine(packaged.stderr)}`;
   }

package/stack/build.mjs

@@ -45,7 +45,7 @@ function ownerOf(ctx, config) {
   return match[1].toLowerCase();
 }
 
-/** The Dockerfile of an app: be/apps/<app>/Dockerfile or fe/apps/<app>/Dockerfile, or db/Dockerfile for the db image; ambiguity and absence are refusals. */
+/** The Dockerfile of an app: be/apps/<app>/Dockerfile or fe/apps/<app>/Dockerfile, or the managed .starcistacks/images/db/Dockerfile for the db image; ambiguity and absence are refusals. */
 function dockerfileOf(config, app) {
   if (app === DB_IMAGE_APP && fs.existsSync(path.join(config.repoRoot, DB_DOCKERFILE))) return DB_DOCKERFILE;
   const found = SIDES.map((side) => `${side}/apps/${app}/Dockerfile`).filter((file) => fs.existsSync(path.join(config.repoRoot, file)));