@starci/hfs 4.11.22 → 4.12.0

package/runtime/scripts/hfs/rules/script-hygiene.mjs

@@ -2,7 +2,6 @@
 // Only source is read. Secret files and sealed envelopes are excluded before any read,
 // and findings carry a path and a fixed explanation, never source text or values.
 import { found, readJson, readText } from './read.mjs';
-
 const PLAINTEXT_LOAD = 'HFS_SCRIPT_PLAINTEXT_LOAD';
 const XTRACE = 'HFS_SCRIPT_XTRACE';
 const SECRET_ENV_FILE = /(?:^|\/)(?:secrets?\.env|\.env)(?:\.[^/]*)?/iu;
@@ -34,125 +33,143 @@ const isLoad = (line) => LOAD_PATTERNS.some((pattern) => pattern.test(line));
 const READ_CALL = /\b(?:readFile(?:Sync)?|readTextFile(?:Sync)?|ReadAllText|ReadAllLines|load_dotenv|loadEnvFile|dotenv\s*\.\s*(?:config|parse))\s*\(/giu;
 const TRACE_COMMAND = /(?:^|[\s;&|('"`]|#!)(?:set|\/?(?:[\w.-]+\/)*(?:bash|sh|dash|zsh|ksh))\s+/giu;
 const SHELL_OPTIONS = /\bSHELLOPTS\s*=\s*['"]?([^\s;'"]*)/giu;
-
 /** Retain executable strings, including remote shell commands, but discard comment-only lines. */
 function executableText(text) {
-  return text.replace(/\/\*[\s\S]*?\*\//gu, '').split(/\r?\n/u)
-    .filter((line) => !/^\s*(?:#(?!!)|\/\/)/u.test(line)).join('\n')
-    .replace(/[\\`]\r?\n/gu, ' ');
+    return text.replace(/\/\*[\s\S]*?\*\//gu, '').split(/\r?\n/u)
+        .filter((line) => !/^\s*(?:#(?!!)|\/\/)/u.test(line)).join('\n')
+        .replace(/[\\`]\r?\n/gu, ' ');
 }
-
 const hasSecretReference = (text) => SECRET_REFERENCE.test(text.replace(EXAMPLE_REFERENCE, 'example-file'));
-
 function callArguments(text, from) {
-  let depth = 1;
-  let quote = '';
-  for (let at = from; at < Math.min(text.length, from + 1024); at += 1) {
-    const character = text[at];
-    if (character === '\\') { at += 1; continue; }
-    if (quote) { if (character === quote) { quote = ''; } continue; }
-    if (['\'', '"', '`'].includes(character)) { quote = character; continue; }
-    if (character === '(') depth += 1;
-    if (character === ')' && --depth === 0) return text.slice(from, at);
-  }
-  return '';
+    let depth = 1;
+    let quote = '';
+    for (let at = from; at < Math.min(text.length, from + 1024); at += 1) {
+        const character = text[at];
+        if (character === '\\') {
+            at += 1;
+            continue;
+        }
+        if (quote) {
+            if (character === quote) {
+                quote = '';
+            }
+            continue;
+        }
+        if (['\'', '"', '`'].includes(character)) {
+            quote = character;
+            continue;
+        }
+        if (character === '(')
+            depth += 1;
+        if (character === ')' && --depth === 0)
+            return text.slice(from, at);
+    }
+    return '';
 }
-
 /** A helper may assign a path first and source/read the variable on the next line. */
 function secretAliases(lines) {
-  const aliases = [];
-  for (const line of lines) {
-    const equals = line.indexOf('=');
-    if (equals < 0 || !hasSecretReference(line.slice(equals + 1))) continue;
-    const name = line.slice(0, equals).trim().replace(/^(?:export|const|let|var)\s+/iu, '').replace(/^\$/u, '');
-    if (/^[a-z_]\w*$/iu.test(name)) aliases.push(new RegExp(String.raw`\b${name}\b`, 'u'));
-  }
-  return aliases;
+    const aliases = [];
+    for (const line of lines) {
+        const equals = line.indexOf('=');
+        if (equals < 0 || !hasSecretReference(line.slice(equals + 1)))
+            continue;
+        const name = line.slice(0, equals).trim().replace(/^(?:export|const|let|var)\s+/iu, '').replace(/^\$/u, '');
+        if (/^[a-z_]\w*$/iu.test(name))
+            aliases.push(new RegExp(String.raw `\b${name}\b`, 'u'));
+    }
+    return aliases;
 }
-
 /** JS, .NET and dotenv readers can put their filename on a later line of the call. */
 function multilineLoad(text, secretReference) {
-  for (const match of text.matchAll(READ_CALL)) {
-    const args = callArguments(text, match.index + match[0].length);
-    if (secretReference(args)) return true;
-  }
-  return false;
+    for (const match of text.matchAll(READ_CALL)) {
+        const args = callArguments(text, match.index + match[0].length);
+        if (secretReference(args))
+            return true;
+    }
+    return false;
 }
-
 function pythonLoad(text) {
-  // Python's default open mode is reading; explicit write/append modes are not loads.
-  for (const match of text.matchAll(/\bopen\s*\(/gu)) {
-    const args = callArguments(text, match.index + match[0].length).split(',').map((value) => value.trim());
-    const filename = /^(['"])([^'"\r\n]+)\1$/u.exec(args[0]);
-    const mode = /^(['"])([^'"]*)\1$/u.exec(args[1] ?? '');
-    if (filename && (!args[1] || mode && /^[rU]/u.test(mode[2])) && hasSecretReference(filename[2])) return true;
-  }
-  return false;
+    // Python's default open mode is reading; explicit write/append modes are not loads.
+    for (const match of text.matchAll(/\bopen\s*\(/gu)) {
+        const args = callArguments(text, match.index + match[0].length).split(',').map((value) => value.trim());
+        const filename = /^(['"])([^'"\r\n]+)\1$/u.exec(args[0]);
+        const mode = /^(['"])([^'"]*)\1$/u.exec(args[1] ?? '');
+        if (filename && (!args[1] || mode && /^[rU]/u.test(mode[2])) && hasSecretReference(filename[2]))
+            return true;
+    }
+    return false;
 }
-
 function plaintextLoad(text) {
-  const lines = text.split(/\r?\n/u);
-  const aliases = secretAliases(lines);
-  const secretReference = (value) => hasSecretReference(value) || aliases.some((alias) => alias.test(value));
-  return lines.some((line) => isLoad(line) && secretReference(line)) || multilineLoad(text, secretReference) || pythonLoad(text);
+    const lines = text.split(/\r?\n/u);
+    const aliases = secretAliases(lines);
+    const secretReference = (value) => hasSecretReference(value) || aliases.some((alias) => alias.test(value));
+    return lines.some((line) => isLoad(line) && secretReference(line)) || multilineLoad(text, secretReference) || pythonLoad(text);
 }
-
 function tracingOptions(source) {
-  let previous = '';
-  for (const [token] of source.matchAll(/[^\s;'"})`]+/gu)) {
-    if (!token.startsWith('-')) {
-      if (!previous || !/^[\w-]+$/u.test(token)) return false;
-      if (/^-o$/iu.test(previous) && /^xtrace$/iu.test(token)) return true;
-      previous = '';
-      continue;
+    let previous = '';
+    for (const [token] of source.matchAll(/[^\s;'"})`]+/gu)) {
+        if (!token.startsWith('-')) {
+            if (!previous || !/^[\w-]+$/u.test(token))
+                return false;
+            if (/^-o$/iu.test(previous) && /^xtrace$/iu.test(token))
+                return true;
+            previous = '';
+            continue;
+        }
+        if (!/^--?[\w-]+$/u.test(token))
+            return false;
+        if (/^-[a-z]+$/iu.test(token) && token.toLowerCase().includes('x'))
+            return true;
+        previous = token;
     }
-    if (!/^--?[\w-]+$/u.test(token)) return false;
-    if (/^-[a-z]+$/iu.test(token) && token.toLowerCase().includes('x')) return true;
-    previous = token;
-  }
-  return false;
+    return false;
 }
-
 /** Parse shell options individually so repeated flags cannot create regex backtracking. */
 function enablesTracing(text) {
-  if (/--reveal\b/iu.test(text)) return true;
-  for (const match of text.matchAll(SHELL_OPTIONS)) {
-    if (/\bxtrace\b/iu.test(match[1])) return true;
-  }
-  for (const match of text.matchAll(TRACE_COMMAND)) {
-    const from = match.index + match[0].length;
-    const newline = text.indexOf('\n', from);
-    if (tracingOptions(text.slice(from, newline < 0 ? text.length : newline))) return true;
-  }
-  return false;
+    if (/--reveal\b/iu.test(text))
+        return true;
+    for (const match of text.matchAll(SHELL_OPTIONS)) {
+        if (/\bxtrace\b/iu.test(match[1]))
+            return true;
+    }
+    for (const match of text.matchAll(TRACE_COMMAND)) {
+        const from = match.index + match[0].length;
+        const newline = text.indexOf('\n', from);
+        if (tracingOptions(text.slice(from, newline < 0 ? text.length : newline)))
+            return true;
+    }
+    return false;
 }
-
 function isSource(file) {
-  if (isSecretFile(file) || EXCLUDED_TREE.test(file) || TEST_FILE.test(file)) return false;
-  return SOURCE.test(file) || WORKFLOW.test(file) || DOCKER.test(file)
-    || file.endsWith('/package.json') || file === 'package.json'
-    || (DELIVERY.test(file) && !/\.[a-z0-9]+$/iu.test(file));
+    if (isSecretFile(file) || EXCLUDED_TREE.test(file) || TEST_FILE.test(file))
+        return false;
+    return SOURCE.test(file) || WORKFLOW.test(file) || DOCKER.test(file)
+        || file.endsWith('/package.json') || file === 'package.json'
+        || (DELIVERY.test(file) && !/\.[a-z0-9]+$/iu.test(file));
 }
-
 function sourceText(repoRoot, file) {
-  if (file === 'package.json' || file.endsWith('/package.json')) {
-    const scripts = readJson(repoRoot, file)?.scripts;
-    return scripts && typeof scripts === 'object' ? Object.values(scripts).filter((value) => typeof value === 'string').join('\n') : null;
-  }
-  return readText(repoRoot, file);
+    if (file === 'package.json' || file.endsWith('/package.json')) {
+        const scripts = readJson(repoRoot, file)?.scripts;
+        return scripts && typeof scripts === 'object' ? Object.values(scripts).filter((value) => typeof value === 'string').join('\n') : null;
+    }
+    return readText(repoRoot, file);
 }
-
 /** Both editions share this custody boundary; the app root scans `all` once, including its sides. */
-export function scriptHygieneFindings({ repoRoot, files = [], all = files, repo, resolver, isRoot, inScope = () => true }) {
-  if (repo?.kind !== 'app' || !['lite', 'full'].includes(repo.edition) || isRoot === false) return [];
-  const findings = [];
-  for (const file of new Set(all)) {
-    if (!inScope(file) || !isSource(file)) continue;
-    const raw = sourceText(repoRoot, file);
-    if (raw === null) continue;
-    const text = executableText(raw);
-    if (plaintextLoad(text)) findings.push(found(PLAINTEXT_LOAD, file, 'Executable source loads a plaintext secret file; use starci app secret with sealed envelopes.'));
-    if (enablesTracing(text)) findings.push(found(XTRACE, file, 'Executable source enables shell tracing or secret reveal; remove xtrace and --reveal.'));
-  }
-  return findings;
+export function scriptHygieneFindings({ repoRoot, files = [], all = files, repo, isRoot, inScope = () => true }) {
+    if (repo?.kind !== 'app' || !['lite', 'full'].some((value) => value === repo.edition) || isRoot === false)
+        return [];
+    const findings = [];
+    for (const file of new Set(all)) {
+        if (!inScope(file) || !isSource(file))
+            continue;
+        const raw = sourceText(repoRoot, file);
+        if (raw === null)
+            continue;
+        const text = executableText(raw);
+        if (plaintextLoad(text))
+            findings.push(found(PLAINTEXT_LOAD, file, 'Executable source loads a plaintext secret file; use starci app secret with sealed envelopes.'));
+        if (enablesTracing(text))
+            findings.push(found(XTRACE, file, 'Executable source enables shell tracing or secret reveal; remove xtrace and --reveal.'));
+    }
+    return findings;
 }

package/runtime/scripts/hfs/rules/secret-custody-only.d.mts

@@ -0,0 +1,7 @@
+import type { Repo } from './rule-types.mjs';
+export declare function secretCustodyOnlyFindings({ repoRoot, files, repo, inScope }: {
+    repoRoot: string;
+    files: string[];
+    repo: Repo;
+    inScope: (file: string) => boolean;
+}): import("./rule-types.mjs").Finding[];

package/runtime/scripts/hfs/rules/secret-custody-only.mjs

@@ -8,10 +8,8 @@
 // FORBIDDEN_FILES; this rule refuses the names R06's path list does not name. A finding never carries a value.
 import { secretHits, secretNameLike } from '../../lib/secret-patterns.mjs';
 import { found, readText } from './read.mjs';
-
 const PLAINTEXT_FILE = 'HFS_SECRET_PLAINTEXT_FILE';
 const OUTSIDE_ENC = 'HFS_SECRET_OUTSIDE_ENC';
-
 // `secrets.env` at any depth, plus `.secret.env`/`.secrets.env` - a dotenv file named for what it holds.
 const SECRET_ENV = /(?:^|\/)\.?secrets?\.env$/i;
 // A non-dot `<name>.env` or `<name>.env.<profile>` tracked file (deploy/prod.env, config.env.local); the
@@ -22,44 +20,40 @@ const ENV_FILE = /(?:^|\/)[^/.][^/]*\.env(?:\.(?!example|sample|template)[^/]*)?
 const SECRETS_DIR = /(?:^|\/)secrets\/[^/]+\.(?:ya?ml|env|json|conf|cfg|ini|toml|txt|properties)$/i;
 const SEALED_DIR = /^\.starcistacks\/[^/]+\/secrets\//;
 const SEALED_HOME = /^\.starcistacks\/[^/]+\/secrets\/[^/]+\.enc(?:\.yaml)?$/;
-
 const KEY_LINE = /^\s*(?:export\s+)?([A-Za-z_$][\w$]*)\s*=/;
-const hasSecretKeys = (file, text) =>
-  text.split(/\r?\n/).some((line) => {
+const hasSecretKeys = (file, text) => text.split(/\r?\n/).some((line) => {
     const key = KEY_LINE.exec(line);
     return (key && secretNameLike(key[1])) || secretHits(file, line).length > 0;
-  });
-
+});
 const sealedCustodyFindings = (file, posix, repo) => {
-  if (SEALED_HOME.test(posix) || repo.edition === 'lite') return [];
-  return [found(OUTSIDE_ENC, file,
-    `${file} is a sealed secret outside .starcistacks/<env>/secrets/; only that directory may hold committed secret envelopes`)];
+    if (SEALED_HOME.test(posix) || repo.edition === 'lite')
+        return [];
+    return [found(OUTSIDE_ENC, file, `${file} is a sealed secret outside .starcistacks/<env>/secrets/; only that directory may hold committed secret envelopes`)];
 };
-
 export function secretCustodyOnlyFindings({ repoRoot, files, repo, inScope }) {
-  const findings = [];
-  for (const file of files.filter((f) => !inScope || inScope(f))) {
-    const posix = file.replaceAll('\\', '/');
-    if (/\.enc(?:\.yaml)?$/.test(file)) {
-      findings.push(...sealedCustodyFindings(file, posix, repo));
-      continue;
+    const findings = [];
+    for (const file of files.filter((f) => !inScope || inScope(f))) {
+        const posix = file.replaceAll('\\', '/');
+        if (/\.enc(?:\.yaml)?$/.test(file)) {
+            findings.push(...sealedCustodyFindings(file, posix, repo));
+            continue;
+        }
+        if (SEALED_DIR.test(posix))
+            continue;
+        if (SECRET_ENV.test(posix)) {
+            findings.push(found(PLAINTEXT_FILE, file, `${file} is a tracked plaintext secrets dotenv; seal secrets with starci app secret set --env <env> into .starcistacks/<env>/secrets/<slug>.enc - never commit the plaintext`));
+            continue;
+        }
+        if (SECRETS_DIR.test(posix)) {
+            findings.push(found(PLAINTEXT_FILE, file, `${file} is a tracked plaintext file inside a secrets/ directory; seal secrets with sops into .starcistacks/<env>/secrets/<slug>.enc - never commit the plaintext`));
+            continue;
+        }
+        if (!ENV_FILE.test(posix))
+            continue;
+        const text = readText(repoRoot, file);
+        if (text === null || !hasSecretKeys(file, text))
+            continue;
+        findings.push(found(PLAINTEXT_FILE, file, `${file} is a tracked dotenv file holding secret keys; seal secrets with sops into .starcistacks/<env>/secrets/<slug>.enc - never commit the plaintext`));
     }
-    if (SEALED_DIR.test(posix)) continue;
-    if (SECRET_ENV.test(posix)) {
-      findings.push(found(PLAINTEXT_FILE, file,
-        `${file} is a tracked plaintext secrets dotenv; seal secrets with starci app secret set into .starcistacks/<env>/secrets/<slug>.enc - never commit the plaintext`));
-      continue;
-    }
-    if (SECRETS_DIR.test(posix)) {
-      findings.push(found(PLAINTEXT_FILE, file,
-        `${file} is a tracked plaintext file inside a secrets/ directory; seal secrets with sops into .starcistacks/<env>/secrets/<slug>.enc - never commit the plaintext`));
-      continue;
-    }
-    if (!ENV_FILE.test(posix)) continue;
-    const text = readText(repoRoot, file);
-    if (text === null || !hasSecretKeys(file, text)) continue;
-    findings.push(found(PLAINTEXT_FILE, file,
-      `${file} is a tracked dotenv file holding secret keys; seal secrets with sops into .starcistacks/<env>/secrets/<slug>.enc - never commit the plaintext`));
-  }
-  return findings;
+    return findings;
 }

package/runtime/scripts/hfs/rules/secrets.d.mts

@@ -0,0 +1,29 @@
+import type { Parsed, Repo, Resolver } from './rule-types.mjs';
+/** True when the slot `id` of the manifest reports HFS_PLAINTEXT_SECRET for the paths it forbids. */
+export declare const slotOwnsSecrets: (slot: Parsed) => boolean;
+/** A legacy lite root secrets.env is reported even when ignored; its presence is enough, so no value is read. */
+export declare function untrackedSecretFindings({ repoRoot, files, repo }: {
+    repoRoot: string;
+    files: string[];
+    repo: Repo;
+}): import("./rule-types.mjs").Finding[];
+/**
+ * The findings of R06 for one tracked file that no forbidden slot claims: a secret by being (an env file, a key file), an `.enc` that is
+ * no sops envelope, or a line that matches a secret pattern. `text` is the file's text, or null when it cannot be read (binary, too
+ * large, absent). The whole-tree check reads the work tree and the commit hook (`starci app check --staged`) reads the staged blob: one judgement.
+ */
+export declare function secretFileFindings({ file, text, manifestText }: {
+    file: string;
+    text: string | null;
+    manifestText?: string | null | undefined;
+}): import("./rule-types.mjs").Finding[];
+/** The findings of R06 over `files` (tracked paths) of `repoRoot`; `resolver` names the slots. */
+export declare function secretFindings({ repoRoot, files, resolver }: {
+    repoRoot: string;
+    files: string[];
+    resolver: Resolver;
+}): import("./rule-types.mjs").Finding[];
+export declare function ageKeyCustodyFindings({ files, inScope }: {
+    files: string[];
+    inScope: (file: string) => boolean;
+}): import("./rule-types.mjs").Finding[];

package/runtime/scripts/hfs/rules/secrets.mjs

@@ -10,70 +10,71 @@ import path from 'node:path';
 import { FORBIDDEN_FILES, secretHitsInFile } from '../../lib/secret-patterns.mjs';
 import { isSopsEnvelope } from '../../lib/sops-envelope.mjs';
 import { found, readText } from './read.mjs';
-
 const PLAINTEXT_SECRET = 'HFS_PLAINTEXT_SECRET';
 /** Files whose lines are not secrets: a lockfile carries integrity hashes, never a credential. */
 const NOT_SCANNED = /(^|\/)package-lock\.json$/;
-
 /** True when the slot `id` of the manifest reports HFS_PLAINTEXT_SECRET for the paths it forbids. */
 export const slotOwnsSecrets = (slot) => slot?.rules?.includes(PLAINTEXT_SECRET) === true;
-
 /** A legacy lite root secrets.env is reported even when ignored; its presence is enough, so no value is read. */
 export function untrackedSecretFindings({ repoRoot, files, repo }) {
-  if (repo.profile !== 'app' || repo.edition !== 'lite' || files.includes('secrets.env')) return [];
-  try {
-    if (!fs.statSync(path.join(repoRoot, 'secrets.env')).isFile()) return [];
-  } catch {
-    return [];
-  }
-  return [found(PLAINTEXT_SECRET, 'secrets.env', 'secrets.env is an untracked plaintext secret at the lite app root; seal it with starci app secret set into .starcistacks/<env>/secrets/<slug>.enc and remove the plaintext file; read materialized values by *_FILE', { level: 'warning', pattern: 'untracked-secrets-env' })];
+    if (repo.profile !== 'app' || repo.edition !== 'lite' || files.includes('secrets.env'))
+        return [];
+    try {
+        if (!fs.statSync(path.join(repoRoot, 'secrets.env')).isFile())
+            return [];
+    }
+    catch {
+        return [];
+    }
+    return [found(PLAINTEXT_SECRET, 'secrets.env', 'secrets.env is an untracked plaintext secret at the lite app root; seal it with starci app secret set --env <env> into .starcistacks/<env>/secrets/<slug>.enc and remove the plaintext file; read materialized values by *_FILE', { level: 'warning', pattern: 'untracked-secrets-env' })];
 }
-
 /**
  * The findings of R06 for one tracked file that no forbidden slot claims: a secret by being (an env file, a key file), an `.enc` that is
  * no sops envelope, or a line that matches a secret pattern. `text` is the file's text, or null when it cannot be read (binary, too
- * large, absent). The whole-tree check reads the work tree and the commit hook (`starci app hygiene`) reads the staged blob: one judgement.
+ * large, absent). The whole-tree check reads the work tree and the commit hook (`starci app check --staged`) reads the staged blob: one judgement.
  */
 export function secretFileFindings({ file, text, manifestText }) {
-  const being = FORBIDDEN_FILES.find((rule) => rule.test(file));
-  if (being) return [found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret by being (${being.name}); a secret is committed only as a sops envelope at .starcistacks/<env>/secrets/<slug>.enc`, { pattern: being.name })];
-  if (text === null || text === undefined || NOT_SCANNED.test(file)) return [];
-  if (/\.enc(?:\.yaml)?$/.test(file)) return isSopsEnvelope(text) ? [] : [found(PLAINTEXT_SECRET, file, `${file} is named like a sealed secret but is not a sops envelope; encrypt the value with sops and commit only the envelope`, { pattern: 'sops-not-envelope' })];
-  const findings = [];
-  const seen = new Set();
-  for (const { line, pattern } of secretHitsInFile(file, text, { manifestText })) {
-    if (seen.has(pattern)) continue;
-    seen.add(pattern);
-    findings.push(found(PLAINTEXT_SECRET, file, `${file}:${line} holds a plaintext secret (${pattern}); seal it with sops at .starcistacks/<env>/secrets/<slug>.enc and read it by *_FILE`, { line, pattern }));
-  }
-  return findings;
+    const being = FORBIDDEN_FILES.find((rule) => rule.test(file));
+    if (being)
+        return [found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret by being (${being.name}); a secret is committed only as a sops envelope at .starcistacks/<env>/secrets/<slug>.enc`, { pattern: being.name })];
+    if (text === null || text === undefined || NOT_SCANNED.test(file))
+        return [];
+    if (/\.enc(?:\.yaml)?$/.test(file))
+        return isSopsEnvelope(text) ? [] : [found(PLAINTEXT_SECRET, file, `${file} is named like a sealed secret but is not a sops envelope; encrypt the value with sops and commit only the envelope`, { pattern: 'sops-not-envelope' })];
+    const findings = [];
+    const seen = new Set();
+    for (const { line, pattern } of secretHitsInFile(file, text, typeof manifestText === 'string' ? { manifestText } : {})) {
+        if (seen.has(pattern))
+            continue;
+        seen.add(pattern);
+        findings.push(found(PLAINTEXT_SECRET, file, `${file}:${line} holds a plaintext secret (${pattern}); seal it with sops at .starcistacks/<env>/secrets/<slug>.enc and read it by *_FILE`, { line, pattern }));
+    }
+    return findings;
 }
-
 /** The findings of R06 over `files` (tracked paths) of `repoRoot`; `resolver` names the slots. */
 export function secretFindings({ repoRoot, files, resolver }) {
-  const findings = [];
-  for (const file of files) {
-    const slot = resolver.classifyPath(file);
-    if (slot.status === 'forbidden' && slotOwnsSecrets(resolver.slot(slot.slot))) {
-      const destination = slot.goesTo ? `; it belongs at ${slot.goesTo}` : '';
-      findings.push(found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret file tracked in ${slot.slot}${destination}`, { slot: slot.slot, goesTo: slot.goesTo }));
-      continue;
+    const findings = [];
+    for (const file of files) {
+        const slot = resolver.classifyPath(file);
+        if (slot.status === 'forbidden' && slotOwnsSecrets(resolver.slot(slot.slot))) {
+            const destination = slot.goesTo ? `; it belongs at ${slot.goesTo}` : '';
+            findings.push(found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret file tracked in ${slot.slot}${destination}`, { slot: slot.slot, goesTo: slot.goesTo }));
+            continue;
+        }
+        const manifestText = /(?:^|\/)README\.md$/.test(file) ? readText(repoRoot, path.posix.join(path.posix.dirname(file), '.starcistacks/application-stacks.yaml')) : undefined;
+        findings.push(...secretFileFindings({ file, text: readText(repoRoot, file), manifestText }));
     }
-    const manifestText = /(?:^|\/)README\.md$/.test(file) ? readText(repoRoot, path.posix.join(path.posix.dirname(file), '.starcistacks/application-stacks.yaml')) : undefined;
-    findings.push(...secretFileFindings({ file, text: readText(repoRoot, file), manifestText }));
-  }
-  return findings;
+    return findings;
 }
-
 // The age identity stays on the host: `.claude/secret.env` (SOPS_AGE_KEY) or the sops config dir's `keys.txt`,
 // both host-local files. A tracked `secret.env`, `keys.txt` or `*.agekey` is the identity committed.
 const AGE_KEY_FILE = /^\.claude\/secret\.env$|(?:^|\/)keys\.txt$|\.agekey$/i;
 export function ageKeyCustodyFindings({ files, inScope }) {
-  const findings = [];
-  for (const file of files.filter((f) => !inScope || inScope(f))) {
-    if (!AGE_KEY_FILE.test(file)) continue;
-    findings.push(found('HFS_AGE_KEY_CUSTODY', file,
-      `${file} is a tracked sops/age identity file; the age key lives only in the host-local .claude/secret.env or the sops keys.txt - never commit the identity`));
-  }
-  return findings;
+    const findings = [];
+    for (const file of files.filter((f) => !inScope || inScope(f))) {
+        if (!AGE_KEY_FILE.test(file))
+            continue;
+        findings.push(found('HFS_AGE_KEY_CUSTODY', file, `${file} is a tracked sops/age identity file; the age key lives only in the host-local .claude/secret.env or the sops keys.txt - never commit the identity`));
+    }
+    return findings;
 }

package/runtime/scripts/hfs/rules/services.d.mts

@@ -0,0 +1,7 @@
+import type { Repo } from './rule-types.mjs';
+/** Every finding of the microservice policy over the app at `repoRoot`; `files` are its tracked app-relative paths. */
+export declare function serviceFindings({ repoRoot, files, repo }: {
+    repoRoot: string;
+    files: string[];
+    repo: Repo;
+}): import("./rule-types.mjs").Finding[];