@starci/hfs 4.3.0 → 4.4.1

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

@@ -53,69 +53,70 @@ export const fileOf = (directory, slug) => {
   return path.join(directory, `${slug}.enc`);
 };
 
-/** Seal `key = value` into the secret `slug`: an existing document keeps its other keys and its recipients. */
-export function writeSecret({ file, values, age, sops }) {
-  for (const key of Object.keys(values)) validateKey(key);
-  const held = claimFile(path.resolve(file));
-  if (!held.ok)
-    throw new SecretError(
-      "the sealed secret is being updated; retry after that write settles",
-    );
+/** Build and validate a replacement envelope without publishing it. */
+function sealSecretMap({ file, values, age, sops }) {
+  let map = Object.create(null);
+  let recipients = age;
+  if (fs.existsSync(file)) {
+    const envelope = envelopeOf(fs.readFileSync(file, "utf8"));
+    map = sops.decrypt(file, envelope.format);
+    if (!age.length) recipients = envelope.recipients;
+  }
+  validateMap(map);
+  map = { ...map, ...values };
+  const sealed = sops.seal({ inputType: "dotenv", plaintext: plaintextOf("dotenv", map), recipients, filenameOverride: file });
+  let parsed;
+  try { parsed = envelopeOf(sealed); }
+  catch { throw new SecretError("sops returned an invalid sealed document"); }
+  if (!isSopsEnvelope(sealed) || parsed.keys.length !== Object.keys(map).length || !parsed.keys.every((key) => Object.hasOwn(map, key)))
+    throw new SecretError("sops returned an invalid sealed document");
+  return sealed;
+}
+
+/** Publish through an explicit file owner, or the canonical atomic replace. */
+function publishSealed(file, sealed, write) {
+  if (write) { write(file, sealed); return; }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = path.join(path.dirname(file), "." + path.basename(file) + "-" + randomUUID() + ".tmp");
   try {
-    const format = "dotenv";
-    let map = Object.create(null);
-    let recipients = age;
-    if (fs.existsSync(file)) {
-      const text = fs.readFileSync(file, "utf8");
-      const envelope = envelopeOf(text);
-      map = sops.decrypt(file, envelope.format);
-      if (!age.length) recipients = envelope.recipients;
-    }
-    validateMap(map);
-    map = { ...map, ...values };
-    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");
-    }
-    if (
-      !isSopsEnvelope(sealed) ||
-      parsed.keys.length !== Object.keys(map).length ||
-      !parsed.keys.every((key) => Object.hasOwn(map, key))
-    )
-      throw new SecretError("sops returned an invalid sealed document");
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    const temporary = path.join(
-      path.dirname(file),
-      `.${path.basename(file)}-${randomUUID()}.tmp`,
-    );
-    try {
-      fs.writeFileSync(temporary, sealed, {
-        flag: "wx",
-        mode: 0o600,
-        flush: true,
-      });
-      fs.renameSync(temporary, file);
-    } finally {
-      if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
-    }
+    fs.writeFileSync(temporary, sealed, { flag: "wx", mode: 0o600, flush: true });
+    fs.renameSync(temporary, file);
   } finally {
-    held.release();
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
   }
 }
 
+function underClaim(file, action) {
+  const held = claimFile(path.resolve(file));
+  if (!held.ok)
+    throw new SecretError("the sealed secret is being updated; retry after that write settles");
+  try {
+    action();
+  } finally { held.release(); }
+}
+
+/** Replace one existing sealed member with an already validated envelope: same claim and atomic publish as set. */
+export const replaceSealed = (file, sealed) => underClaim(file, () => publishSealed(file, sealed));
+
+/** Delete one sealed member under the writer claim. */
+export const deleteSealed = (file) => underClaim(file, () => fs.unlinkSync(file));
+
+/** Seal named values; a supplied writer owns its own claim and rollback (the fresh-app scaffold). */
+export function writeSecret({ file, values, age, sops, write }) {
+  for (const key of Object.keys(values)) validateKey(key);
+  const held = write ? { ok: true, release() {} } : claimFile(path.resolve(file));
+  if (!held.ok)
+    throw new SecretError("the sealed secret is being updated; retry after that write settles");
+  try {
+    publishSealed(file, sealSecretMap({ file, values, age, sops }), write);
+  } finally { held.release(); }
+}
+
 /** Update named keys through the same canonical sealed-secret owner used by the CLI. */
 export function setSecretValues(
   repoRoot,
   { slug, values, env = null },
-  { sops = null, age = [], processEnv = process.env } = {},
+  { sops = null, age = [], processEnv = process.env, write } = {},
 ) {
   const directory = secretsDirectory(repoRoot, env);
   const file = fileOf(directory, slug);
@@ -134,6 +135,7 @@ export function setSecretValues(
     values,
     age,
     sops: sops ?? defaultSops(processEnv, repoRoot),
+    write,
   });
   return { file, via: "sealed-secret" };
 }

package/runtime/scripts/hfs/secret.mjs

@@ -1,6 +1,8 @@
-// secret.mjs - app secret init|set|get|materialize|list: sealed custody and private KEY files.
+// 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.
 // 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).
 import fs from "node:fs";
 import path from "node:path";
 import { randomBytes } from "node:crypto";
@@ -11,11 +13,14 @@ 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";
 
 export { envelopeOf, formatOf, plaintextOf } from "./secret-document.mjs";
 export { setSecretValues } from "./secret-store.mjs";
 
-const VERBS = new Set(["init", "list", "get", "set", "materialize"]);
+const VERBS = new Set(["init", "list", "get", "set", "unset", "rename", "remove", "materialize", "verify"]);
+const EDIT_VERBS = new Set(["unset", "rename", "remove"]);
 
 function valueOption(opts, flag, value) {
   if (value === undefined || value.startsWith("--"))
@@ -32,7 +37,7 @@ function parse(argv) {
     const [flag, inline] = arg.split(/=(.*)/su);
     if (["--cwd", "--generate"].includes(flag)) {
       valueOption(opts, flag, inline ?? argv[++i]);
-    } else if (["--to-file", "--reveal"].includes(flag)) {
+    } else if (["--to-file", "--reveal", "--execute", "--force-nonempty"].includes(flag)) {
       if (inline !== undefined && !["true", "false"].includes(inline))
         throw new SecretError(`${flag} expects true or false`);
       opts[flag.slice(2)] = inline !== "false";
@@ -55,9 +60,19 @@ function usageArguments(verb) {
   if (verb === "init") return "";
   if (verb === "set") return "<env> <slug> <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]";
   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["force-nonempty"] !== undefined && verb !== "remove")
+    throw new SecretError("--force-nonempty is only valid for remove");
+}
+
 function outputOptionsFor(verb, opts) {
   if (
     (opts["to-file"] !== undefined || opts.reveal !== undefined) &&
@@ -74,8 +89,12 @@ function optionsFor(verb, opts) {
     init: [0, 0],
     list: [1, 1],
     materialize: [1, 1],
+    verify: [1, 1],
     set: [3, 3],
     get: [2, 3],
+    unset: [3, 3],
+    rename: [4, 4],
+    remove: [2, 2],
   }[verb];
   if (count < bounds[0] || count > bounds[1])
     throw new SecretError(
@@ -84,6 +103,8 @@ function optionsFor(verb, opts) {
   if (opts.generate !== undefined && verb !== "set")
     throw new SecretError("--generate is only valid for set");
   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 === "get" && opts.positional[2] !== undefined)
     validateKey(opts.positional[2]);
@@ -130,7 +151,7 @@ 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 | materialize <env> | list <env>",
+        "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>",
       );
     const opts = parse(rest);
     optionsFor(verb, opts);
@@ -142,7 +163,15 @@ export function secretMain(
     const [environment, slug, key] = opts.positional;
     const directory = secretsDirectory(repoRoot, environment);
     if (verb === "list") return listSecrets(directory, stdout);
-    const seam = sops ?? defaultSops(env, repoRoot, platform, tools);
+    const open = () => sops ?? defaultSops(env, repoRoot, platform, tools);
+    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,
+      });
+    const seam = open();
+    if (verb === "verify")
+      return verifySecrets({ repoRoot, directory, environment, sops: seam, stdout });
     const output = { repoRoot, environment, env, platform, stdout };
     if (verb === "materialize")
       return materializeSecrets(directory, seam, output);

package/runtime/scripts/hfs/slot-imports.mjs

@@ -2,9 +2,14 @@
 // owner units, the layer order and the public entry of an owner. Cycles are a graph property of the architecture check, not of one edge.
 import { RUNTIME_KIND } from './manifest-shape.mjs';
 import { classifyIn, ownerIn, tierIn } from './slot-classify.mjs';
+import { braceVariants, globExpression } from '../lib/glob.mjs';
 
 const isEntryFile = (name) => name === 'index.ts' || name === 'index.tsx';
 
+function declaredEntry(slot, relative) {
+  return (slot.entries ?? []).some(entry => braceVariants(entry).some(pattern => globExpression(pattern).test(relative)));
+}
+
 function unownedPathProblem(from, to) {
   for (const side of [from, to]) {
     if (side.status === 'no-slot') return { allowed: false, reason: 'unowned', code: side.code, path: side.path, nearest: side.nearest };
@@ -39,12 +44,22 @@ function privateEntryProblem({ repo, byId }, to, toOwner) {
   if (toOwner && repo.kind !== RUNTIME_KIND) {
     const relative = to.path === toOwner.root ? '' : to.path.slice(toOwner.root.length + 1);
     const ownerSlot = byId.get(toOwner.slot);
-    const entry = isEntryFile(relative) || (byId.get(to.slot).entries ?? []).includes(to.path.slice(to.root.length + 1)) || (ownerSlot.tier === 'package' && relative === 'src/index.ts') || (ownerSlot.tier === 'app' && relative === 'app.module.ts');
+    const entry = isEntryFile(relative) || declaredEntry(byId.get(to.slot), to.path.slice(to.root.length + 1)) || (ownerSlot.tier === 'package' && relative === 'src/index.ts') || (ownerSlot.tier === 'app' && relative === 'app.module.ts');
     if (!entry) return { allowed: false, reason: 'notPublicEntry', owner: toOwner.root, path: to.path };
   }
   return null;
 }
 
+function tierImportProblem(scope, from, to, fromTier, toTier) {
+  const { mayImport, mayImportKinds, mayImportSlots } = scope.manifest.tiers[scope.profile][fromTier] ?? {};
+  if (!mayImport?.includes(toTier)) return { allowed: false, reason: 'tierDirection', fromTier, toTier, mayImport: mayImport ?? [] };
+  const kindRestriction = mayImportKinds?.[toTier];
+  if (kindRestriction && (!kindRestriction.from.includes(from.kind) || !kindRestriction.to.includes(to.kind))) return { allowed: false, reason: 'tierDirection', fromTier, toTier, mayImport, kindRestriction, fromKind: from.kind ?? null, toKind: to.kind ?? null };
+  const slotRestriction = mayImportSlots?.[toTier];
+  if (slotRestriction && !slotRestriction.from.includes(from.slot)) return { allowed: false, reason: 'tierDirection', fromTier, toTier, mayImport, slotRestriction, fromSlot: from.slot };
+  return null;
+}
+
 /**
  * Whether `fromPath` may import `toPath`: {allowed, reason, ...}. Reasons: sameOwner, untiered, crossApp,
  * tierDirection, layerOrder, notPublicEntry, allowed, slotForbidden, slotNotEnabled, slotAmbiguous, and unowned (HFS_SLOT_UNDECLARED for the path no slot owns).
@@ -65,10 +80,8 @@ export function importAllowedIn(scope, fromPath, toPath) {
   const fromOwner = ownerIn(scope, from.path);
   const toOwner = ownerIn(scope, to.path);
   if (sameOwnerUnit(from, fromOwner) === sameOwnerUnit(to, toOwner)) return { allowed: true, reason: 'sameOwner' };
-  const { mayImport, mayImportKinds } = scope.manifest.tiers[scope.profile][fromTier] ?? {};
-  if (!mayImport?.includes(toTier)) return { allowed: false, reason: 'tierDirection', fromTier, toTier, mayImport: mayImport ?? [] };
-  const kindRestriction = mayImportKinds?.[toTier];
-  if (kindRestriction && (!kindRestriction.from.includes(from.kind) || !kindRestriction.to.includes(to.kind))) return { allowed: false, reason: 'tierDirection', fromTier, toTier, mayImport, kindRestriction, fromKind: from.kind ?? null, toKind: to.kind ?? null };
+  const tierProblem = tierImportProblem(scope, from, to, fromTier, toTier);
+  if (tierProblem) return tierProblem;
   const layerProblem = lowerLayerProblem(scope, from, to, fromTier, toTier, fromOwner, toOwner);
   if (layerProblem) return layerProblem;
   // A runtime owner is imported file by file (crossOwner of knowledge/hfs/runtime-slots.yaml): no public entry.

package/runtime/scripts/hfs/slots.mjs

@@ -5,7 +5,7 @@
 //   is this path tracked             isTracked(P) / trackingOf(P); the rule catalog (knowledge/hfs/rules.yaml, modules/schemas/hfs-rules.schema.yaml) loads through loadRuleCatalog / rules().
 // Every check and lint rule of HFS reads knowledge/hfs/slots.yaml through this module; none keeps its own path
 // list. The manifest shape is modules/schemas/hfs-slots.schema.yaml and hfs.json is modules/schemas/hfs-repo.schema.yaml;
-// the installed runtime carries no npm dependency, so this file re-states those shapes instead of loading ajv (tests/hfs/hfs-slots.spec.mjs proves the two agree).
+// the installed runtime carries no npm dependency, so this file re-states those shapes instead of loading ajv.
 //
 // A product is ONE app repository: hfs.json at the app root has kind `app` and declares its two sides, `be` and `fe`, each in
 // the folder of that name. The resolver of the app answers for the whole tree: a root path with the slots of profile `app`,
@@ -41,7 +41,7 @@ export { HfsSlotsError } from './slot-errors.mjs';
 export { loadRuleCatalog };
 export { rules } from './rule-catalog.mjs';
 export { APP_SCOPE };
-export const HFS_MANIFEST_FILE = 'knowledge/hfs/slots.yaml';
+const HFS_MANIFEST_FILE = 'knowledge/hfs/slots.yaml';
 /** The manifest of kind runtime: the standard tree of the StarCi runtime repository (judged by scripts/hfs/runtime-check.mjs). */
 export const RUNTIME_MANIFEST_FILE = 'knowledge/hfs/runtime-slots.yaml';
 export const HFS_DECLARATION_FILE = 'hfs.json';
@@ -119,6 +119,7 @@ function sideDeclaration(manifest, declaration, name, edition, providers) {
     connections: Object.freeze((s.connections ?? []).map(connectionView)),
     providers,
     reads: Object.freeze([...(s.reads ?? [])]),
+    ...(s.extraPackages === undefined ? {} : { extraPackages: Object.freeze(s.extraPackages.map(entry => Object.freeze({ ...entry }))) }),
     manifestVersion: manifest.version,
   });
 }

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

@@ -0,0 +1,34 @@
+// stack-config-kit.mjs - the small validators the deploy block (stack-deploy-config.mjs) and its ingress block (stack-ingress-config.mjs)
+// share: a problem collector, closed field lists, pattern checks and the environment-relative file check.
+import path from 'node:path';
+import { isPlainObject as plain } from '../../engine/plain-object.mjs';
+
+const BACKSLASH = String.fromCodePoint(92);
+
+/** Collects problems with the path they concern; `problem(at, message)` is the only way to add one. */
+export function collector() {
+  const problems = [];
+  return { problems, problem: (at, message) => { problems.push({ at, message }); } };
+}
+
+/** True for a mapping; reports every key outside `allowed` as "not a field of the <label> block". */
+export function closedFields(c, at, value, allowed, label = 'deploy') {
+  if (!plain(value)) { c.problem(at, 'must be a mapping'); return false; }
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) c.problem(`${at}.${key}`, `is not a field of the ${label} block`);
+  return true;
+}
+
+/** True when `value` is a string matching `pattern`; otherwise reports it. */
+export function patternField(c, at, value, pattern) {
+  if (typeof value !== 'string' || !pattern.test(value)) { c.problem(at, `must match ${pattern}`); return false; }
+  return true;
+}
+
+/** A path inside .starcistacks/<env>/ : relative, forward slashes, no `..`, and present in the tree. */
+export function treeFile(c, at, value, probe) {
+  if (typeof value !== 'string' || value === '' || path.posix.isAbsolute(value) || value.includes(BACKSLASH) || path.posix.normalize(value).split('/').includes('..')) {
+    c.problem(at, 'must be a relative path inside the environment directory');
+    return;
+  }
+  if (!probe.exists(value)) c.problem(at, `${value} does not exist under the environment directory`);
+}