@starci/hfs 4.3.0 → 4.4.0

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

@@ -0,0 +1,237 @@
+// stack-ingress-config.mjs - the reader of `environments.<env>.deploy.ingress`: the SHARED host ingress (80/443) of the VPS. The ingress is
+// its own swarm stack (`name`) owning the attachable overlay and the host-mode ports; the app stack consumes it. External (non-swarm, plain
+// docker compose) tenants are reached over the overlay by a UNIQUE alias, or by a host address (`hostAddress`).
+// Pure given the block and a probe of the app tree. `normalizeDeploy` (stack-deploy-config.mjs) hooks it in as `config.ingress`;
+// `starci app stack ingress plan|attach|takeover` (packages/hfs/stack/ingress.mjs) consumes the normalised result.
+import { closedFields, collector, patternField, treeFile } from './stack-config-kit.mjs';
+import { isPlainObject as plain } from '../../engine/plain-object.mjs';
+import { NAME } from './stack-deploy-config.mjs';
+
+const DOCKER_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/u;
+const REMOTE_PATH = /^\/[A-Za-z0-9._/-]+$/u;
+const DNS_LABEL = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?';
+const DNS_HOST = new RegExp(String.raw`^${DNS_LABEL}(?:\.${DNS_LABEL})+$`, 'u');
+const PINNED_IMAGE = /^[a-z0-9./_-]+(?::[A-Za-z0-9._-]+)?@sha256:(?!0{64}$)[0-9a-f]{64}$/u;
+const TRAEFIK_ARG = /^--[A-Za-z0-9][A-Za-z0-9.-]*(?:=[^\s]*)?$/u;
+const OCTET = String.raw`(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)`;
+const IPV4 = new RegExp(String.raw`^${OCTET}(?:\.${OCTET}){3}$`, 'u');
+const URL_PATH = /^\/[A-Za-z0-9._~%/-]*$/u;
+const REDIRECT_STATUS = [301, 302, 303, 307, 308];
+
+const FIELDS = {
+  ingress: ['name', 'image', 'args', 'network', 'acmeVolume', 'service', 'legacy', 'upstreams', 'routes', 'middlewares', 'verify', 'drop', 'redirects', 'backup', 'publish', 'takeover'],
+  legacy: ['dir', 'dynamicDir', 'container'],
+  upstream: ['name', 'hosts', 'container', 'hostAddress', 'port', 'aliases', 'middlewares'],
+  verify: ['host', 'path', 'status'],
+  redirect: ['host', 'to', 'status'],
+  backup: ['dir'],
+  publish: ['file', 'supersedes'],
+  takeover: ['gateSeconds', 'rehearsalPorts'],
+  ports: ['http', 'https'],
+};
+
+const closed = (c, at, value, allowed) => closedFields(c, at, value, allowed, 'ingress');
+const matching = patternField;
+
+function remotePath(c, at, value) {
+  if (typeof value !== 'string' || !REMOTE_PATH.test(value) || value.split('/').includes('..')) c.problem(at, 'must be an absolute path without ..');
+}
+
+function port(c, at, value) {
+  if (!(Number.isInteger(value) && value >= 1 && value <= 65535)) c.problem(at, 'must be a port from 1 to 65535');
+}
+
+function httpStatus(c, at, value) {
+  if (!(Number.isInteger(value) && value >= 100 && value <= 599)) c.problem(at, 'must be an HTTP status code');
+}
+
+function list(c, at, value, check) {
+  if (!Array.isArray(value) || value.length === 0) { c.problem(at, 'must be a non-empty list'); return []; }
+  value.forEach((item, index) => check(`${at}[${index}]`, item));
+  return value;
+}
+
+const names = (c, pattern) => (where, item) => { matching(c, where, item, pattern); };
+
+function legacy(c, block) {
+  if (!closed(c, 'deploy.ingress.legacy', block, FIELDS.legacy)) return null;
+  remotePath(c, 'deploy.ingress.legacy.dir', block.dir);
+  remotePath(c, 'deploy.ingress.legacy.dynamicDir', block.dynamicDir);
+  matching(c, 'deploy.ingress.legacy.container', block.container, DOCKER_NAME);
+  return { dir: block.dir, dynamicDir: block.dynamicDir, container: block.container };
+}
+
+/** An upstream is a container on the overlay (alias = the route target) or a host address (`hostAddress`), never both. */
+function target(c, at, entry) {
+  if ((entry.container === undefined) === (entry.hostAddress === undefined)) c.problem(at, 'declare exactly one of container and hostAddress');
+  if (entry.container !== undefined) matching(c, `${at}.container`, entry.container, DOCKER_NAME);
+  if (entry.hostAddress !== undefined) matching(c, `${at}.hostAddress`, entry.hostAddress, IPV4);
+  if (entry.hostAddress !== undefined && entry.aliases !== undefined) c.problem(`${at}.aliases`, 'a hostAddress upstream has no alias');
+  if (entry.container === undefined) return [];
+  return entry.aliases === undefined ? [entry.name] : list(c, `${at}.aliases`, entry.aliases, names(c, DOCKER_NAME));
+}
+
+function upstream(c, at, entry) {
+  if (!closed(c, at, entry, FIELDS.upstream)) return null;
+  matching(c, `${at}.name`, entry.name, NAME);
+  port(c, `${at}.port`, entry.port);
+  const aliases = target(c, at, entry);
+  // an attach-only upstream (a container the tenants' own route files reach, with no host of its own) declares no hosts
+  const hosts = entry.hosts === undefined ? [] : list(c, `${at}.hosts`, entry.hosts, names(c, DNS_HOST));
+  const middlewareNames = entry.middlewares === undefined ? [] : list(c, `${at}.middlewares`, entry.middlewares, names(c, NAME));
+  return {
+    name: entry.name, hosts, container: entry.container ?? null, hostAddress: entry.hostAddress ?? null, port: entry.port, aliases, middlewares: middlewareNames,
+  };
+}
+
+function duplicates(c, label, values, at) {
+  const seen = new Set();
+  for (const value of values) {
+    if (seen.has(value)) c.problem(at, `${label} ${value} is declared more than once`);
+    seen.add(value);
+  }
+}
+
+function upstreams(c, block) {
+  if (block === undefined) return [];
+  const out = list(c, 'deploy.ingress.upstreams', block, () => {}).map((entry, index) => upstream(c, `deploy.ingress.upstreams[${index}]`, entry)).filter(Boolean);
+  duplicates(c, 'upstream name', out.map((entry) => entry.name), 'deploy.ingress.upstreams');
+  duplicates(c, 'host', out.flatMap((entry) => entry.hosts), 'deploy.ingress.upstreams');
+  duplicates(c, 'alias (aliases must be unique on the shared overlay)', out.flatMap((entry) => entry.aliases), 'deploy.ingress.upstreams');
+  return out;
+}
+
+function middlewareMap(c, block) {
+  if (block === undefined) return {};
+  if (!plain(block)) { c.problem('deploy.ingress.middlewares', 'must be a mapping of name to middleware'); return {}; }
+  const out = {};
+  for (const [name, value] of Object.entries(block)) {
+    const at = `deploy.ingress.middlewares.${name}`;
+    if (!matching(c, at, name, NAME)) continue;
+    if (plain(value)) out[name] = value;
+    else c.problem(at, 'must be a mapping');
+  }
+  return out;
+}
+
+function referencedMiddlewares(c, ups, declared, routes) {
+  if (routes !== null) return;
+  ups.forEach((entry, index) => {
+    for (const name of entry.middlewares) {
+      if (!Object.hasOwn(declared, name)) c.problem(`deploy.ingress.upstreams[${index}].middlewares`, `middleware ${name} is not declared in deploy.ingress.middlewares`);
+    }
+  });
+}
+
+function verifyList(c, block) {
+  if (block === undefined) return [];
+  return list(c, 'deploy.ingress.verify', block, () => {}).flatMap((entry, index) => {
+    const at = `deploy.ingress.verify[${index}]`;
+    if (!closed(c, at, entry, FIELDS.verify)) return [];
+    matching(c, `${at}.host`, entry.host, DNS_HOST);
+    if (entry.path !== undefined) matching(c, `${at}.path`, entry.path, URL_PATH);
+    if (entry.status !== undefined) httpStatus(c, `${at}.status`, entry.status);
+    return [{ host: entry.host, path: entry.path ?? '/', status: entry.status ?? null }];
+  });
+}
+
+function dropList(c, block) {
+  return block === undefined ? [] : list(c, 'deploy.ingress.drop', block, names(c, DNS_HOST));
+}
+
+function redirects(c, block) {
+  if (block === undefined) return [];
+  return list(c, 'deploy.ingress.redirects', block, () => {}).flatMap((entry, index) => {
+    const at = `deploy.ingress.redirects[${index}]`;
+    if (!closed(c, at, entry, FIELDS.redirect)) return [];
+    matching(c, `${at}.host`, entry.host, DNS_HOST);
+    matching(c, `${at}.to`, entry.to, DNS_HOST);
+    if (entry.status !== undefined && !REDIRECT_STATUS.includes(entry.status)) c.problem(`${at}.status`, `must be one of ${REDIRECT_STATUS.join(', ')}`);
+    return [{ host: entry.host, to: entry.to, status: entry.status ?? 301 }];
+  });
+}
+
+function backup(c, block) {
+  if (block === undefined) return null;
+  if (!closed(c, 'deploy.ingress.backup', block, FIELDS.backup)) return null;
+  remotePath(c, 'deploy.ingress.backup.dir', block.dir);
+  return { dir: block.dir };
+}
+
+const ROUTE_FILE = /^[a-z][a-z0-9-]*.ya?ml$/u;
+
+/** Where the app's own routes file lands in the shared directory, and the generic old file names it replaces (both required when declared). */
+function publish(c, block) {
+  if (block === undefined) return null;
+  const at = 'deploy.ingress.publish';
+  if (!closed(c, at, block, FIELDS.publish)) return null;
+  matching(c, `${at}.file`, block.file, ROUTE_FILE);
+  const supersedes = list(c, `${at}.supersedes`, block.supersedes, (where, name) => {
+    if (matching(c, where, name, ROUTE_FILE) && name === block.file) c.problem(where, 'must differ from publish.file');
+  });
+  duplicates(c, 'superseded file', supersedes, `${at}.supersedes`);
+  return { file: block.file, supersedes };
+}
+
+const DEFAULT_REHEARSAL_PORTS = { http: 18080, https: 18443 };
+
+/** Alternate host ports of the rehearsal: valid ports, never the production 80 and 443, and different from each other. */
+function rehearsalPorts(c, block) {
+  const at = 'deploy.ingress.takeover.rehearsalPorts';
+  if (block === undefined) return { ...DEFAULT_REHEARSAL_PORTS };
+  if (!closed(c, at, block, FIELDS.ports)) return { ...DEFAULT_REHEARSAL_PORTS };
+  for (const key of FIELDS.ports) {
+    port(c, `${at}.${key}`, block[key]);
+    if ([80, 443].includes(block[key])) c.problem(`${at}.${key}`, 'must not be the production port 80 or 443');
+  }
+  if (block.http === block.https) c.problem(at, 'http and https must differ');
+  return { http: block.http, https: block.https };
+}
+
+function takeover(c, block) {
+  if (block === undefined) return { gateSeconds: 30, rehearsalPorts: { ...DEFAULT_REHEARSAL_PORTS } };
+  if (!closed(c, 'deploy.ingress.takeover', block, FIELDS.takeover)) return null;
+  const gate = block.gateSeconds ?? 30;
+  if (!(Number.isInteger(gate) && gate >= 1 && gate <= 300)) c.problem('deploy.ingress.takeover.gateSeconds', 'must be a whole number of seconds from 1 to 300');
+  return { gateSeconds: gate, rehearsalPorts: rehearsalPorts(c, block.rehearsalPorts) };
+}
+
+/**
+ * Validates and normalises one `deploy.ingress` block (undefined -> { ingress: null, problems: [] }).
+ *   probe.exists(rel)  does a file exist below .starcistacks/<env>/ ?
+ * Returns { ingress, problems }; ingress is null when a problem was found.
+ */
+export function normalizeIngress(block, { probe }) {
+  const c = collector();
+  if (block === undefined) return { ingress: null, problems: [] };
+  if (!closed(c, 'deploy.ingress', block, FIELDS.ingress)) return { ingress: null, problems: c.problems };
+  for (const key of ['name', 'service']) if (block[key] !== undefined) matching(c, `deploy.ingress.${key}`, block[key], NAME);
+  if (block.image !== undefined) matching(c, 'deploy.ingress.image', block.image, PINNED_IMAGE);
+  const args = block.args === undefined ? null : list(c, 'deploy.ingress.args', block.args, names(c, TRAEFIK_ARG));
+  matching(c, 'deploy.ingress.network', block.network, DOCKER_NAME);
+  matching(c, 'deploy.ingress.acmeVolume', block.acmeVolume, DOCKER_NAME);
+  if (block.routes !== undefined) treeFile(c, 'deploy.ingress.routes', block.routes, probe);
+  const ups = upstreams(c, block.upstreams);
+  const declared = middlewareMap(c, block.middlewares);
+  const routes = block.routes ?? null;
+  referencedMiddlewares(c, ups, declared, routes);
+  const ingress = {
+    name: block.name ?? 'ingress',
+    image: block.image ?? null,
+    args,
+    service: block.service ?? 'ingress',
+    network: block.network,
+    acmeVolume: block.acmeVolume,
+    legacy: legacy(c, block.legacy),
+    upstreams: ups,
+    routes,
+    middlewares: declared,
+    verify: verifyList(c, block.verify),
+    drop: dropList(c, block.drop),
+    redirects: redirects(c, block.redirects),
+    backup: backup(c, block.backup),
+    publish: publish(c, block.publish),
+    takeover: takeover(c, block.takeover),
+  };
+  return { ingress: c.problems.length === 0 ? ingress : null, problems: c.problems };
+}

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

@@ -0,0 +1,414 @@
+import { composeEntries } from '../lib/compose-values.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { lsFiles } from '../api/git/ls-files.mjs';
+import {parseYaml} from '../../engine/yaml.mjs';
+import {slash} from '../lib/path-key.mjs';
+import { isInside, walkFiles } from '../lib/walk.mjs';
+import { composeIncludePaths, swarmInventoryIssues, swarmModelIssues } from '../lib/swarm-stack.mjs';
+import { swarmHardeningIssues } from './rules/stacks-swarm.mjs';
+import { ingressIssues } from './rules/stacks-ingress.mjs';
+import { liteBackingIssues } from './rules/stacks-lite-backing.mjs';
+import { releaseBackupIssues, scheduleIssues } from './rules/stacks-release.mjs';
+import { stacksDeploymentContexts } from './rules/stacks-runtime.mjs';
+import { appEdition, applicationStackFindings, liteCustodyDirectory } from './starcistacks-runtime.mjs';
+
+const RESULT='starci/application-stacks-check@1';
+const STACKS_DIR='.starcistacks';
+const MAX_INPUT_BYTES=4*1024*1024;
+const SCHEMA_ID='starci/application-stacks@1';
+const RUNBOOK_COMMANDS=['prepare','doctor','up','status','logs','down','verification'];
+const PLAINTEXT_SECRET_PATTERN=/\.(key|pem|p12|pfx)$/i;
+const inside=(root,target)=>isInside(path.resolve(root),path.resolve(target));
+const object=value=>value&&typeof value==='object'&&!Array.isArray(value);
+const sensitive=/pass(word)?|secret|token|credential|private[_-]?key|api[_-]?key/i;
+const nonempty=value=>typeof value==='string'&&Boolean(value.trim());
+const manifestSchema=parseYaml(fs.readFileSync(new URL('../../modules/schemas/application-stacks.schema.yaml',import.meta.url),'utf8'));
+const HARDENING_CODES=new Set([
+  'STACKS_SECRET_NOT_EXTERNAL','STACKS_SECRET_UNVERSIONED','STACKS_SECRET_ENV_LITERAL','STACKS_PORT_PUBLISHED',
+  'STACKS_SECOND_INGRESS','STACKS_DNS_UNDECLARED','STACKS_HOST_UNROUTED','STACKS_TLS_UNDECLARED',
+  'STACKS_PLACEMENT_MISSING','STACKS_HEALTHCHECK_MISSING','STACKS_UPDATE_POLICY_MISSING','STACKS_REALTIME_SCALED',
+  'STACKS_RELEASE_UNDECLARED','BACKUP_UNDECLARED','BACKUP_PROOF_MISSING','STACKS_MODEL_UNAVAILABLE',
+  'HFS_SCHEDULE_UNDECLARED','STACKS_INGRESS_UNDECLARED','STACKS_INGRESS_UNKNOWN',
+  'STACKS_LITE_SELFHOSTED_DB','STACKS_SIDECAR_VOLUME_UNDECLARED','STACKS_SIDECAR_DB_UNSUPPORTED',
+]);
+
+function regular(file,{root=null}={}){
+  try{
+    const stat=fs.lstatSync(file);if(!stat.isFile()||stat.isSymbolicLink())return false;
+    return !root||inside(root,fs.realpathSync(file));
+  }catch{return false;}
+}
+function directory(file){try{return fs.lstatSync(file).isDirectory()&&!fs.lstatSync(file).isSymbolicLink();}catch{return false;}}
+function safeAncestors(root,target){
+  if(!inside(root,target))return false;
+  let cursor=path.resolve(target),base=path.resolve(root);
+  while(cursor!==base){
+    if(fs.existsSync(cursor)&&fs.lstatSync(cursor).isSymbolicLink())return false;
+    cursor=path.dirname(cursor);
+  }
+  return true;
+}
+function resolvedPath(base,relative){
+  if(!nonempty(relative)||path.isAbsolute(relative)||String(relative).split(/[\\/]/).includes('..'))return null;
+  const target=path.resolve(base,String(relative));return inside(base,target)&&safeAncestors(base,target)?target:null;
+}
+
+function validateSchema(value){
+  const errors=[],isObject=value=>value!==null&&typeof value==='object'&&!Array.isArray(value),resolve=ref=>ref.slice(2).split('/').reduce((node,key)=>node?.[key],manifestSchema);
+  const typeOk=(node,type)=>{
+    if(type==='object')return isObject(node);
+    if(type==='array')return Array.isArray(node);
+    if(type==='integer')return Number.isInteger(node);
+    if(type)return typeof node===type;
+    return true;
+  };
+  const checkString=(node,shape,at)=>{
+    if(shape.minLength&&node.length<shape.minLength)errors.push({path:at,message:'string too short'});
+    if(shape.pattern&&!new RegExp(shape.pattern,'u').test(node))errors.push({path:at,message:'pattern mismatch'});
+  };
+  const checkNumber=(node,shape,at)=>{
+    if(shape.minimum!==undefined&&node<shape.minimum)errors.push({path:at,message:'number below minimum'});
+    if(shape.maximum!==undefined&&node>shape.maximum)errors.push({path:at,message:'number above maximum'});
+  };
+  const checkObject=(node,shape,at)=>{
+    if(shape.minProperties&&Object.keys(node).length<shape.minProperties)errors.push({path:at,message:'object has too few properties'});
+    for(const key of shape.required??[])if(!Object.hasOwn(node,key))errors.push({path:at,message:`missing ${key}`});
+    for(const [key,child] of Object.entries(node)){
+      if(Object.hasOwn(shape.properties??{},key))check(child,shape.properties[key],`${at}/${key}`);
+      else if(shape.additionalProperties===false)errors.push({path:`${at}/${key}`,message:'unknown field'});
+      else if(isObject(shape.additionalProperties))check(child,shape.additionalProperties,`${at}/${key}`);
+    }
+  };
+  const checkAlternatives=(node,shape,at,check)=>{
+    const matched=shape.anyOf.some((option)=>{
+      const start=errors.length;check(node,option,at);
+      if(errors.length===start)return true;
+      errors.splice(start);return false;
+    });
+    if(!matched)errors.push({path:at,message:'matches none of the allowed shapes'});
+  };
+  const checkArray=(node,shape,at,check)=>{
+    if(shape.minItems&&node.length<shape.minItems)errors.push({path:at,message:'array too short'});
+    node.forEach((item,index)=>shape.items&&check(item,shape.items,`${at}/${index}`));
+  };
+  const check=(node,shape,at)=>{
+    if(shape?.$ref)return check(node,resolve(shape.$ref),at);
+    if(Array.isArray(shape?.anyOf)){
+      checkAlternatives(node,shape,at,check);
+      return;
+    }
+    const typed=typeOk(node,shape?.type);
+    if(!typed){errors.push({path:at,message:`expected ${shape.type}`});return;}
+    if(Object.hasOwn(shape??{},'const')&&node!==shape.const)errors.push({path:at,message:'const mismatch'});
+    if(Array.isArray(shape?.enum)&&!shape.enum.includes(node))errors.push({path:at,message:'value outside enum'});
+    if(typeof node==='string')checkString(node,shape,at);
+    if(typeof node==='number')checkNumber(node,shape,at);
+    if(Array.isArray(node)){
+      checkArray(node,shape,at,check);
+      return;
+    }
+    if(!isObject(node))return;
+    checkObject(node,shape,at);
+  };check(value,manifestSchema,'$');return errors;
+}
+const unresolved=value=>typeof value==='string'&&/(^|[^$])\$\{/.test(value);
+const serviceUnresolved=(service)=>{
+  const build=object(service?.build)?service.build:{context:service?.build};
+  const values=[service?.image,build.context,build.dockerfile,...(Array.isArray(service?.ports)?service.ports:[])];
+  for(const volume of Array.isArray(service?.volumes)?service.volumes:[])values.push(object(volume)?volume.source:String(volume).split(':')[0]);
+  for(const [key,value] of composeEntries(service?.environment, { isMapping: object }))if(!sensitive.test(key))values.push(value);
+  return values.some(unresolved);
+};
+function unresolvedCompose(model){
+  for(const service of Object.values(object(model?.services)?model.services:{})){
+    if(serviceUnresolved(service))return true;
+  }
+  return Object.values(object(model?.secrets)?model.secrets:{}).some(item=>unresolved(item?.file));
+}
+function sopsEnvelope(file){
+  // Recognizes both the YAML/JSON envelope (a "sops" object) and the flattened dotenv envelope SOPS
+  // emits for a .env member (sops_lastmodified=, sops_mac=, sops_age__list_0__map_enc=, ...).
+  try{
+    if(fs.statSync(file).size>MAX_INPUT_BYTES)return false;
+    const text=fs.readFileSync(file,'utf8');
+    return (/(?:(?:^|\n)sops:|["']sops["']\s*:|(?:^|\n)sops_[a-z0-9_]+=)/.test(text))&&/ENC\[AES256_GCM,data:/.test(text);
+  }catch{return false;}
+}
+
+function gitTrackedSet(root){
+  try{
+    const result=lsFiles(['--',STACKS_DIR],{dir:root,timeout:5000});
+    if(result.error||result.status!==0||typeof result.stdout!=='string')return null;
+    return new Set(result.stdout.split(/\r?\n/).filter(Boolean).map(slash));
+  }catch{return null;}
+}
+function composeLike(file){
+  try{
+    if(fs.statSync(file).size>MAX_INPUT_BYTES)return false;
+    const doc=parseYaml(fs.readFileSync(file,'utf8'));
+    return object(doc)&&(object(doc.services)||Array.isArray(doc.include));
+  }catch{return false;}
+}
+function reachableComposeFiles(envDir,entries){
+  const reachable=new Set(),queue=[...entries];
+  while(queue.length){
+    const relative=queue.shift(),target=resolvedPath(envDir,relative);
+    if(!target||reachable.has(target))continue;
+    reachable.add(target);
+    if(!regular(target,{root:envDir}))continue;
+    let doc=null;try{doc=parseYaml(fs.readFileSync(target,'utf8'));}catch{continue;}
+    for(const include of composeIncludePaths(doc??{}).paths)
+      queue.push(path.isAbsolute(include)?include:slash(path.join(path.relative(envDir,path.dirname(target)),include)));
+  }
+  return reachable;
+}
+function scanForUndeclaredCompose(root,envDir,reachable,add,at){
+  const infra=path.join(envDir,'infra');
+  if(!directory(infra))return;
+  const stack=[infra];
+  while(stack.length){
+    const dir=stack.pop();
+    let entries=[];try{entries=fs.readdirSync(dir,{withFileTypes:true});}catch{continue;}
+    for(const entry of entries){
+      const full=path.join(dir,entry.name);
+      if(entry.isSymbolicLink())continue;
+      if(entry.isDirectory()){stack.push(full);continue;}
+      if(!/\.ya?ml$/i.test(entry.name)||reachable.has(full)||!composeLike(full))continue;
+      add('STACKS_UNDECLARED_COMPOSE',at,`${slash(path.relative(root,full))} is a Compose-shaped file under infra/ that is not declared or reachable from composeFiles; the composeFiles list must be the complete list for this environment`);
+    }
+  }
+}
+
+const loadInputs=({manifestFile,deploymentModelFile,errors,add})=>{
+  const input={manifest:{},model:{}};
+  try{if(!errors.some(item=>['manifest-unavailable','input-too-large'].includes(item.code)&&item.path===`${STACKS_DIR}/application-stacks.yaml`))input.manifest=parseYaml(fs.readFileSync(manifestFile,'utf8'));}
+  catch{add('manifest-invalid',`${STACKS_DIR}/application-stacks.yaml`,'manifest YAML could not be parsed');}
+  try{if(!errors.some(item=>['deployment-model-unavailable','input-too-large'].includes(item.code)&&item.path==='deploymentModelFile')){
+    const text=fs.readFileSync(deploymentModelFile,'utf8');try{input.model=JSON.parse(text);}catch{input.model=parseYaml(text);}
+  }}catch{add('deployment-model-invalid','deploymentModelFile','rendered deployment JSON or YAML could not be parsed');}
+  if(!object(input.manifest))input.manifest={};
+  if(!object(input.model))input.model={};
+  return input;
+};
+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&&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`);
+};
+const checkDeclaredEnvironmentDirs=(stacksRoot,environmentNames,add)=>{
+  for(const name of environmentNames)if(!directory(path.join(stacksRoot,name)))add('environment-directory-missing',`${STACKS_DIR}/${name}`,`declared environment ${name} has no directory`);
+};
+const checkStacksTree=({stacksRoot,manifest,environmentNames,add,lite})=>{
+  if(!directory(stacksRoot))return;
+  let entries=[];try{entries=fs.readdirSync(stacksRoot,{withFileTypes:true});}catch{}
+  for(const entry of entries)checkStackEntry(entry,environmentNames,add,{stacksRoot,lite});
+  checkDeclaredEnvironmentDirs(stacksRoot,environmentNames,add);
+  const k8sDir=path.join(stacksRoot,'k8s'),k8sExists=directory(k8sDir);
+  if(manifest.k8s?.status==='supported'&&!k8sExists)add('k8s-directory-missing',`${STACKS_DIR}/k8s`,'k8s.status is supported but .starcistacks/k8s is missing');
+  if(manifest.k8s?.status==='deferred'&&k8sExists)add('k8s-directory-unexpected',`${STACKS_DIR}/k8s`,'k8s.status is deferred, so a .starcistacks/k8s directory contradicts the declaration');
+};
+const checkComposeFiles=({spec,environment,envDir,root,add})=>{
+  const composeFiles=Array.isArray(spec.composeFiles)?spec.composeFiles:[];
+  if(!composeFiles.length)add('compose-files-empty',`environments.${environment}.composeFiles`,'declare at least one environment-relative Compose source file');
+  const safeComposeFiles=[];
+  for(const [index,relative] of composeFiles.entries()){
+    const target=resolvedPath(envDir,relative);
+    if(!target||!regular(target,{root:envDir}))add('compose-path-unsafe',`environments.${environment}.composeFiles[${index}]`,'Compose source must be a regular non-symlink file below the environment directory');
+    else safeComposeFiles.push(relative);
+  }
+  if(directory(envDir)){
+    if(nonempty(spec.renderedModel))safeComposeFiles.push(spec.renderedModel);
+    const reachable=reachableComposeFiles(envDir,safeComposeFiles);
+    scanForUndeclaredCompose(root,envDir,reachable,add,`environments.${environment}.composeFiles`);
+  }
+};
+const checkRunbook=({spec,environment,envDir,add})=>{
+  if(!nonempty(spec.runbook))add('runbook-path-invalid',`environments.${environment}.runbook`,'runbook must name a file inside the environment directory');
+  else{
+    const runbookFile=resolvedPath(envDir,spec.runbook);
+    const oversized=(()=>{try{return fs.statSync(runbookFile).size>MAX_INPUT_BYTES;}catch{return true;}})();
+    if(!runbookFile||!regular(runbookFile,{root:envDir})||oversized)
+      add('runbook-path-invalid',`environments.${environment}.runbook`,'runbook must resolve to an existing regular non-symlink file below the environment directory');
+    else{
+      let text='';try{text=fs.readFileSync(runbookFile,'utf8');}catch{}
+      for(const command of RUNBOOK_COMMANDS){
+        const rowPattern=new RegExp(String.raw`^\s*\|\s*${command}\s*\|`,'im');
+        if(!rowPattern.test(text))add('runbook-command-missing',`environments.${environment}.runbook#${command}`,`runbook must document the ${command} command`);
+      }
+    }
+  }
+};
+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;
+  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');
+  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())
+    add('secret-policy-missing',at,'secret recipient and key custody policies are required');
+  if(tracked&&plain&&tracked.has(slash(path.relative(root,plain))))
+    add('STACKS_PLAINTEXT_SECRET',`${at}.where`,'a decrypted secret member must never be a tracked file; only its .enc member is committed');
+};
+const checkSecrets=({spec,environment,envDir,root,add})=>{
+  const declaredSecrets=Array.isArray(spec.secrets)?spec.secrets:[],secretNames=new Set();
+  const tracked=directory(envDir)?gitTrackedSet(root):null;
+  for(const [index,secret] of declaredSecrets.entries())
+    checkSecret(secret,`environments.${environment}.secrets[${index}]`,{envDir,environment,root,tracked,secretNames,add});
+  if(tracked){
+    const envPrefix=`${slash(path.relative(root,envDir))}/`;
+    for(const relTracked of tracked){
+      if(!relTracked.startsWith(envPrefix))continue;
+      const base=path.basename(relTracked);
+      if(PLAINTEXT_SECRET_PATTERN.test(base)||base==='id_rsa')
+        add('STACKS_PLAINTEXT_SECRET',relTracked,'a tracked file below the environment directory matches a plaintext secret pattern; only <name>.enc may be committed');
+    }
+  }
+};
+const checkEnvironmentSpec=({spec,environment,envDir,ids,root,add})=>{
+  if(spec.status!=='supported')add('environment-unsupported',`environments.${environment}`,'environment must be explicitly supported');
+  if(!['docker-compose','docker-swarm'].includes(spec.runtime))add('runtime-invalid',`environments.${environment}.runtime`,'runtime must be docker-compose or docker-swarm');
+  checkComposeFiles({spec,environment,envDir,root,add});
+  const bindings=object(spec.components)?spec.components:{};
+  for(const id of Object.keys(bindings))if(!ids.has(id))
+    add('binding-component-unknown',`environments.${environment}.components.${id}`,'environment binds a component id that is absent from the top-level inventory');
+  checkRunbook({spec,environment,envDir,add});
+  checkSecrets({spec,environment,envDir,root,add});
+};
+const checkServiceIds=(services,ids,add)=>{
+  for(const service of Object.keys(services))if(!ids.has(service))
+    add('compose-service-unclassified',`services.${service}`,'rendered service name is not a declared component id');
+};
+const checkServiceEnvironment=(services,add)=>{
+  for(const [service,definition] of Object.entries(services))for(const [key] of composeEntries(definition?.environment, { isMapping: object }))
+    if(sensitive.test(key)&&!/_FILE$/i.test(key))add('plaintext-sensitive-environment',`services.${service}.environment.${key}`,'sensitive configuration is present as a direct environment value; value redacted');
+};
+const checkModel=({model,ids,spec,manifest,lite,add})=>{
+  const services=object(model.services)?model.services:{};
+  checkServiceIds(services,ids,add);
+  if(unresolvedCompose(model))add('compose-placeholder-unresolved','composeModel','rendered Compose still contains an unresolved interpolation placeholder in a host-resolved field');
+  checkServiceEnvironment(services,add);
+  if(object(spec)&&spec.runtime==='docker-swarm')for(const issue of swarmModelIssues({model,components:manifest.components,bindings:spec.components,lite}))
+    add('HFS_STACKS_SHAPE',issue.at,issue.message);
+};
+
+const checkInputPaths=({environment,stacksRoot,manifestFile,deploymentModelFile,add})=>{
+  if(!nonempty(environment))add('environment-invalid','environment','environment must name a declared environment');
+  if(!regular(manifestFile,{root:stacksRoot}))add('manifest-unavailable',`${STACKS_DIR}/application-stacks.yaml`,`manifest must be a regular file inside ${STACKS_DIR}`);
+  if(!regular(deploymentModelFile))add('deployment-model-unavailable','deploymentModelFile','rendered deployment evidence must be a regular, non-symlink file');
+  for(const [file,at] of [[manifestFile,`${STACKS_DIR}/application-stacks.yaml`],[deploymentModelFile,'deploymentModelFile']])
+    try{if(fs.statSync(file).size>MAX_INPUT_BYTES)add('input-too-large',at,'input exceeds the 4 MiB static-check limit');}catch{}
+};
+const componentIdsOf=(manifest,add)=>{
+  const catalog=object(manifest.components)?manifest.components:{},ids=new Set(Object.keys(catalog));
+  if(!ids.size)add('components-empty','components','declare at least one applicable application component');
+  for(const id of ids)if(!/^[a-z][a-z0-9-]*$/.test(id))add('component-invalid',`components.${id}`,'component ids must be lowercase kebab-case');
+  return ids;
+};
+const environmentMapOf=(manifest,add)=>{
+  const environments=object(manifest.environments)?manifest.environments:{},environmentNames=new Set(Object.keys(environments));
+  if(!environmentNames.size)add('environments-empty','environments','declare at least one supported environment');
+  return {environments,environmentNames};
+};
+const checkKubernetesDeclaration=(manifest,add)=>{
+  if(!['deferred','supported'].includes(manifest.k8s?.status)||!String(manifest.k8s?.reason??'').trim())
+    add('k8s-status-invalid','k8s','Kubernetes must be explicitly deferred or supported with a reason');
+};
+const checkSelectedEnvironment=({environment,environmentNames,environments,stacksRoot,ids,root,model,manifest,lite,add})=>{
+  if(nonempty(environment)&&!environmentNames.has(String(environment)))
+    add('environment-unknown','environment',`environment must be one the declaration admits: ${[...environmentNames].join(', ')}`);
+  const spec=environments[String(environment)],envDir=path.join(stacksRoot,String(environment??''));
+  if(object(spec))checkEnvironmentSpec({spec,environment,envDir,ids,root,add});
+  checkModel({model,ids,spec,manifest,lite,add});
+};
+const checkStacksManifest=(manifest,model,{stacksRoot,environment,root,repo,add})=>{
+  for(const issue of validateSchema(manifest))add('schema-shape-invalid',issue.path,issue.message);
+  if(manifest.schema!==SCHEMA_ID)add('schema-invalid','schema',`expected ${SCHEMA_ID}`);
+  const ids=componentIdsOf(manifest,add),{environments,environmentNames}=environmentMapOf(manifest,add);
+  const lite=repo.edition==='lite';
+  checkStacksTree({stacksRoot,manifest,environmentNames,add,lite});
+  checkKubernetesDeclaration(manifest,add);
+  for(const issue of swarmInventoryIssues({components:manifest.components,lite}))add('HFS_STACKS_SHAPE',issue.at,issue.message);
+  checkSelectedEnvironment({environment,environmentNames,environments,stacksRoot,ids,root,model,manifest,lite,add});
+};
+
+function deploymentAvailable(model,errors){
+  const invalid=errors.some(item=>item.path==='deploymentModelFile');
+  return !invalid&&object(model.services)&&Object.keys(model.services).length>0&&model.include===undefined;
+}
+
+function diskEvidenceFiles(root){
+  const excluded=new Set(['node_modules','.git','.claude','.aws','.codex']);
+  return walkFiles(root,{ignoreReadErrors:true,exclude:(name,_file,entry)=>entry.isSymbolicLink()||excluded.has(name)})
+    .map(file=>slash(path.relative(root,file)));
+}
+
+function checkSwarmHardening({manifest,model,environment,root,files,repo,errors,add}){
+  const spec=manifest.environments?.[environment];
+  if(spec?.runtime!=='docker-swarm')return;
+  if(!deploymentAvailable(model,errors)){
+    add('STACKS_MODEL_UNAVAILABLE',`environments.${environment}`,'a rendered deployment model with nonempty services is required to judge Swarm safety');
+    return;
+  }
+  const context={doc:manifest,environment,spec,model,repoRoot:root,files,repo};
+  for(const finder of [swarmHardeningIssues,ingressIssues,liteBackingIssues,releaseBackupIssues,scheduleIssues])
+    for(const issue of finder(context))add(issue.code,issue.at,issue.message);
+}
+
+export function checkApplicationStacks({repoRoot,environment,deploymentModelFile,files,repo}={}){
+  const root=path.resolve(String(repoRoot??'')),stacksRoot=path.join(root,STACKS_DIR),manifestFile=path.join(stacksRoot,'application-stacks.yaml'),errors=[];
+  const declaration=repo??{edition:appEdition(root)};
+  const add=(code,at,message)=>errors.push({code,path:at,message});
+  checkInputPaths({environment,stacksRoot,manifestFile,deploymentModelFile,add});
+  const {manifest,model}=loadInputs({manifestFile,deploymentModelFile,errors,add});
+  checkStacksManifest(manifest,model,{stacksRoot,environment,root,repo:declaration,add});
+  checkSwarmHardening({manifest,model,environment,root,files:files??diskEvidenceFiles(root),repo:declaration,errors,add});
+  for(const item of applicationStackFindings(root))add(item.code,item.path,item.message);
+
+  return {schema:RESULT,ok:errors.length===0,environment,manifest:manifestFile,deploymentModel:path.resolve(String(deploymentModelFile??'')),errors,
+    limitations:['static conformance only; Docker was not invoked, host application processes were not started, and remote APIs were not called','the deployment model must be rendered by Docker Compose or Docker Stack tooling; provenance is supplied by the caller and is not independently authenticated','component classification, runbook completeness and secret custody are author assertions checked for consistency and structure, not independently discovered facts','SOPS envelope recognition is structural, not cryptographic verification or decryption','tracked-plaintext detection uses git ls-files when the repository is reachable and is skipped, not assumed clean, when it is not','runbook prepare, doctor and verification commands are declared and documented but not executed']};
+}
+
+const declarationFindingCodes=new Set(['STACKS_RELEASE_UNDECLARED','BACKUP_UNDECLARED','BACKUP_PROOF_MISSING','HFS_SCHEDULE_UNDECLARED']);
+
+function trackedGateFinding(entry,error){
+  let file=entry.file;
+  const code=HARDENING_CODES.has(error.code)?error.code:'HFS_STACKS_SHAPE';
+  const modelPath=/^(?:services(?:\.|$)|secrets(?:\.|$)|composeModel$|deploymentModelFile$)/.test(error.path);
+  if(declarationFindingCodes.has(error.code)||!modelPath&&code==='HFS_STACKS_SHAPE')file=`${STACKS_DIR}/application-stacks.yaml`;
+  if(error.code==='HFS_SCHEDULE_UNDECLARED'){
+    const source=error.path.replace(/:\d+$/,'');
+    if(/\.(?:sql|[cm]?[jt]s)$/.test(source))file=source;
+  }
+  return {code,level:'error',path:file,message:`${file}: ${error.path}: ${error.message}`};
+}
+
+const findingKey=finding=>`${finding.code}\n${slash(finding.path)}\n${finding.message}`;
+
+function trackedGateErrors(entry,context,files){
+  if(entry.unavailable)return [{code:'STACKS_MODEL_UNAVAILABLE',level:'error',path:entry.file,
+    message:`${entry.file}: environments.${entry.environment}: a tracked rendered deployment model is required to judge Swarm safety`}];
+  const result=checkApplicationStacks({repoRoot:context.repoRoot,environment:entry.environment,
+    deploymentModelFile:path.resolve(context.repoRoot,entry.file),files,repo:context.repo});
+  return result.errors.map(error=>trackedGateFinding(entry,error));
+}
+
+/** Run the public gate on the app's tracked rendered Swarm evidence, without duplicating finder results. */
+export function trackedStacksGateFindings(context={}){
+  const {deployments,files}=stacksDeploymentContexts(context),findings=[];
+  const existing=context.existingFindings??[],seen=new Set(existing.map(findingKey));
+  for(const entry of deployments){
+    for(const finding of trackedGateErrors(entry,context,files)){
+      if(context.inScope&&!context.inScope(finding.path))continue;
+      const key=findingKey(finding);
+      if(seen.has(key))continue;
+      seen.add(key);findings.push(finding);
+    }
+  }
+  return findings;
+}