@starci/hfs 4.10.1 → 4.11.8

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

@@ -5,6 +5,7 @@ import { randomUUID } from "node:crypto";
 import { claimFile } from "../api/fs/claim-file.mjs";
 import { isSopsEnvelope } from "../lib/sops-envelope.mjs";
 import { byCodeUnit } from "../lib/list.mjs";
+import { LEGACY_SUFFIX, isLegacyName, isSealedName, memberFile } from "../lib/sealed-member.mjs";
 import {
   envelopeOf,
   plaintextOf,
@@ -50,21 +51,30 @@ export const fileOf = (directory, slug) => {
     throw new SecretError(
       `${slug === undefined ? "a secret name" : slug} is not a secret slug: lowercase letters, digits and dashes`,
     );
-  return path.join(directory, `${slug}.enc`);
+  try { return memberFile(directory, slug); }
+  catch (error) { throw new SecretError(error.message); }
 };
 
-/** Build and validate a replacement envelope without publishing it. */
+/**
+ * Build and validate a replacement envelope without publishing it. An existing member is decrypted only when it holds a key
+ * `values` does not replace; a member whose every key is replaced (the one-key member a `set` re-seals) needs no age identity.
+ */
 function sealSecretMap({ file, values, age, sops }) {
   let map = Object.create(null);
   let recipients = age;
+  const legacy = isLegacyName(path.basename(file));
   if (fs.existsSync(file)) {
     const envelope = envelopeOf(fs.readFileSync(file, "utf8"));
-    map = sops.decrypt(file, envelope.format);
-    if (!age.length) recipients = envelope.recipients;
+    if (!envelope.keys.every((key) => Object.hasOwn(values, key)))
+      map = sops.decrypt(file, envelope.format);
+    if (!age.length && legacy) recipients = envelope.recipients;
   }
   validateMap(map);
   map = { ...map, ...values };
-  const sealed = sops.seal({ inputType: "dotenv", plaintext: plaintextOf("dotenv", map), recipients, filenameOverride: file });
+  // A member is sops YAML, its values double-quoted scalars kept byte for byte, sealed to the recipients its environment's
+  // .sops.yaml rule names (so a re-seal follows a recipients change); a legacy member stays dotenv to its own recipients.
+  const format = legacy ? "dotenv" : "yaml";
+  const sealed = sops.seal({ inputType: format, plaintext: plaintextOf(format, map), recipients, filenameOverride: file });
   let parsed;
   try { parsed = envelopeOf(sealed); }
   catch { throw new SecretError("sops returned an invalid sealed document"); }
@@ -112,14 +122,18 @@ export function writeSecret({ file, values, age, sops, write }) {
   } finally { held.release(); }
 }
 
-/** Update named keys through the same canonical sealed-secret owner used by the CLI. */
+/**
+ * Update named keys through the same canonical sealed-secret owner used by the CLI. `legacy` creates a new member as a dotenv
+ * `.enc`, for the sops-free bootstrap sealer of a fresh scaffold, which writes only that format; `migrate` moves it later.
+ */
 export function setSecretValues(
   repoRoot,
   { slug, values, env = null },
-  { sops = null, age = [], processEnv = process.env, write } = {},
+  { sops = null, age = [], processEnv = process.env, write, legacy = false } = {},
 ) {
   const directory = secretsDirectory(repoRoot, env);
-  const file = fileOf(directory, slug);
+  const existing = fileOf(directory, slug);
+  const file = legacy && !fs.existsSync(existing) ? path.join(directory, `${slug}${LEGACY_SUFFIX}`) : existing;
   if (
     !values ||
     typeof values !== "object" ||
@@ -144,7 +158,7 @@ export function sealedFiles(directory) {
   return fs.existsSync(directory)
     ? fs
         .readdirSync(directory)
-        .filter((name) => name.endsWith(".enc"))
+        .filter(isSealedName)
         .sort(byCodeUnit)
     : [];
 }

package/runtime/scripts/hfs/secret.mjs

@@ -1,5 +1,7 @@
 // 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).
@@ -7,19 +9,23 @@ 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";
 
 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"]);
+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 +41,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"].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"].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 +58,28 @@ 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>]";
   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))
+    throw new SecretError("--execute is only valid for unset, rename, remove, migrate and split");
+  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 +101,15 @@ 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],
   }[verb];
   if (count < bounds[0] || count > bounds[1])
     throw new SecretError(
@@ -105,40 +120,71 @@ 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;
 }
 
-/** All app secrets verbs; stdin, sops, random and tool ports permit isolated custody specs. */
-export function secretMain(
+/** 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 "";
+}
+
+/** 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`;
+}
+
+/**
+ * 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,
@@ -151,24 +197,37 @@ export function secretMain(
   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>]",
       );
     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;
     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 +236,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

@@ -124,16 +124,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

@@ -11,8 +11,6 @@ const BACKING_IMAGE_BROKERS_AND_OTHERS = '(?:cp-)?kafka(?:-native)?|keycloak|min
 const BACKING_IMAGE = new RegExp(`^(?:${BACKING_IMAGE_SQL_AND_CACHE}|${BACKING_IMAGE_BROKERS_AND_OTHERS})$`, 'i');
 const mapping = value => plain(value) ? value : {};
 
-/** True for the one database image a lite app runs (its db component): supabase/postgres, pinned by digest. */
-export const isLiteDatabaseImage = image => typeof image === 'string' && /^supabase\/postgres(?::[^@]+)?@sha256:[a-f0-9]{64}$/i.test(image);
 const present = value => typeof value === 'string' && Boolean(value.trim());
 const configured = value => Object.keys(mapping(value)).length > 0;
 const schedulerImage = image => present(image) && /(?:^|\/)swarm-cronjob(?:[:@]|$)/.test(image);
@@ -52,8 +50,8 @@ export function swarmInventoryIssues({ components, lite = false }) {
   const add = (at, message) => errors.push({ at, message });
   for (const [id, entry] of Object.entries(catalog)) {
     const component = mapping(entry);
-    if (lite && present(component.image) && BACKING_IMAGE.test(repositoryOf(component.image)) && !isLiteDatabaseImage(component.image))
-      add(`components.${id}.image`, 'lite runs no backing image but its db component (supabase/postgres); storage is the external S3 endpoint, identity the API');
+    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 .starcistacks/images/db/Dockerfile builds, storage is the external S3 endpoint, identity the API');
     jobDeclarationIssues(id, component, catalog, add);
   }
   return errors;
@@ -120,8 +118,8 @@ export function swarmModelIssues({ model, components, bindings, lite = false })
       add(`services.${id}.ports`, 'Swarm ports must be an array of published port definitions');
     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)) && !isLiteDatabaseImage(service.image))
-      add(`services.${id}.image`, 'lite stack runs no backing image but its db service (supabase/postgres)');
+    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 .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/add-queue-lite.mjs

@@ -39,8 +39,23 @@ const LITE_TEMPLATES = Object.freeze({
   'jobs/platform/jobs.index.ts.tpl': 'jobs/platform-lite/jobs.index.ts.tpl',
   'jobs/platform/job-claim.service.ts.tpl': 'jobs/platform-lite/job-claim.service.ts.tpl',
   'jobs/platform/job-claim.service.spec.ts.tpl': 'jobs/platform-lite/job-claim.service.spec.ts.tpl',
+  // The jobs module composes the one tick scheduler (R335, ruling:lite-official-postgres-image): ScheduleModule.forRoot() and JobTickService.
+  'jobs/platform/jobs.module.ts.tpl': 'jobs/platform-lite/jobs.module.ts.tpl',
 });
 
+/** The tick scheduler of platform/jobs the lite jobs capability adds beside full's tree: the ticks as data, the scheduler and its spec (R335). */
+const TICK_FILES = Object.freeze([
+  ['be/src/modules/platform/jobs/job-ticks.contracts.ts', 'jobs/platform-lite/job-ticks.contracts.ts.tpl'],
+  ['be/src/modules/platform/jobs/job-tick.service.ts', 'jobs/platform-lite/job-tick.service.ts.tpl'],
+  ['be/src/modules/platform/jobs/job-tick.service.spec.ts', 'jobs/platform-lite/job-tick.service.spec.ts.tpl'],
+]);
+
+/** The tick files of a jobs capability the verb adds for the first time; an app that already has platform/jobs keeps its own. */
+function tickFiles({ beRoot, patterns }) {
+  if (!patterns.includes('fenced-job') || fs.existsSync(path.join(beRoot, 'src', 'modules', 'platform', 'jobs', 'index.ts'))) return [];
+  return TICK_FILES.map(([relative, source]) => ({ relative, text: template(`be/patterns/${source}`) }));
+}
+
 /**
  * The persistence files lite leaves out: the TypeORM schema (its authority is db/migrations) and the SQL text and row files (the
  * statements are database functions of the lite migration, called through callDbFunction; R334 and the be.persistence lite overlay).
@@ -102,20 +117,24 @@ function migrationFiles({ repoRoot, beRoot, patterns, now }) {
 
 /** The queue imports bullmq, which loads ioredis as an optional peer and cannot connect without it. */
 const QUEUE_CLIENTS = Object.freeze(['bullmq', 'ioredis']);
+/** The jobs capability's tick scheduler imports @nestjs/schedule and its CronJob (R335). */
+const SCHEDULER_CLIENTS = Object.freeze(['@nestjs/schedule', 'cron']);
 
 /**
- * hfs.json declares redis in sides.be.backing; the package.json gains the queue's clients at their canon pins, and the managed
+ * hfs.json declares redis in sides.be.backing; the package.json gains the queue's clients (and, for fenced-job, the tick
+ * scheduler's) at their canon pins, and the managed
  * development scripts of the declared Redis that `starci app sync` renders for it. Each is added when it is missing, so a Redis an
  * earlier capability declared (a cache on ioredis) still gains bullmq; a file already complete is left alone.
  */
-function declarationPatches(repoRoot, project) {
+function declarationPatches(repoRoot, project, patterns) {
   const file = path.join(repoRoot, 'hfs.json');
   const declaration = JSON.parse(read(file));
   declaration.sides.be.backing = [...new Set([...(declaration.sides.be.backing ?? []), 'redis'])].sort(byCodeUnit);
   const packageFile = path.join(repoRoot, 'package.json');
   const pkg = JSON.parse(read(packageFile));
   const pins = bundledPins();
-  const missing = QUEUE_CLIENTS.filter((name) => typeof pkg.dependencies?.[name] !== 'string');
+  const clients = [...QUEUE_CLIENTS, ...(patterns.includes('fenced-job') ? SCHEDULER_CLIENTS : [])];
+  const missing = clients.filter((name) => typeof pkg.dependencies?.[name] !== 'string');
   for (const name of missing) if (!pins[name]) throw new ScaffoldError('HFS_SCAFFOLD_PIN_MISSING', `${name} has no canon pin in knowledge/hfs/canon-pins.yaml`);
   if (missing.length)
     pkg.dependencies = Object.fromEntries(Object.entries({ ...pkg.dependencies, ...Object.fromEntries(missing.map((name) => [name, pins[name].version])) }).sort(([a], [b]) => a.localeCompare(b)));
@@ -331,9 +350,9 @@ export function planLiteQueue({ repoRoot, repo, noun, patterns, now }) {
   const beRoot = path.join(repoRoot, 'be');
   const migrations = migrationFiles({ repoRoot, beRoot, patterns, now });
   const database = skeletonFiles(repoRoot);
-  const declaration = declarationPatches(repoRoot, repo.project);
+  const declaration = declarationPatches(repoRoot, repo.project, patterns);
   const stack = stackFiles(repoRoot, { project: repo.project, consumers: queueServicesOf(repo) });
-  const created = [...migrations, ...database.created, ...stack.created];
+  const created = [...migrations, ...tickFiles({ beRoot, patterns }), ...database.created, ...stack.created];
   const patches = [...database.patches, ...declaration, ...stack.patches];
   const clashes = created.filter((entry) => fs.existsSync(path.join(repoRoot, ...entry.relative.split('/')))).map((entry) => entry.relative);
   if (clashes.length) throw new ScaffoldError('HFS_ADD_EXISTS', `add ${noun} would overwrite ${clashes.join(', ')}`);

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,