@starci/hfs 4.2.17 → 4.4.0

package/runtime/scripts/hfs/rules/database-sql.mjs

@@ -62,18 +62,69 @@ function searchPathSchema(node, current) {
 function addTableFacts(statement, node, facts, defaultSchema) {
   const relation = statement.type === 'CreateStmt' ? node.relation : node.into?.rel;
   if (!relation || node.partbound || relation.relpersistence === 't') return;
+  if (node.objtype === ['OBJECT', 'MATVIEW'].join('_')) {
+    facts.views.push({ ...relationFact(statement, relation, defaultSchema), kind: 'materialized', securityInvoker: false, node });
+    return;
+  }
   facts.tables.push({ schema: schemaOf(relation, defaultSchema), name: relation.relname, index: statement.index, line: statement.line });
 }
 
+const relationFact = (statement, relation, defaultSchema) => ({
+  schema: schemaOf(relation, defaultSchema), name: relation?.relname, index: statement.index, line: statement.line,
+});
+
+const rlsCommands = new Map([
+  ['AT_EnableRowSecurity', { enabled: true }], ['AT_DisableRowSecurity', { enabled: false }],
+  ['AT_ForceRowSecurity', { forced: true }], ['AT_NoForceRowSecurity', { forced: false }],
+]);
+
 function addAlterTableFacts(statement, node, facts, defaultSchema) {
   for (const command of node.cmds ?? []) {
-    const subtype = command?.AlterTableCmd?.subtype;
-    const item = { schema: schemaOf(node.relation, defaultSchema), name: node.relation?.relname, index: statement.index };
+    const alteration = command?.AlterTableCmd;
+    const subtype = alteration?.subtype;
+    const item = relationFact(statement, node.relation, defaultSchema);
     if (subtype === 'AT_EnableRowSecurity') facts.enables.push(item);
     else if (subtype === 'AT_ForceRowSecurity') facts.forces.push(item);
+    const event = rlsCommands.get(subtype);
+    if (event) facts.rlsEvents.push({ ...item, ...event });
+    if (subtype === 'AT_ChangeOwner') facts.owners.push({ ...item, role: alteration.newowner?.rolename });
   }
 }
 
+function addViewFacts(statement, node, facts, defaultSchema) {
+  const security = (node.options ?? []).find((option) => option?.DefElem?.defname === 'security_invoker')?.DefElem?.arg;
+  const securityInvoker = security?.Boolean?.boolval === true || security?.String?.sval === 'true';
+  facts.views.push({ ...relationFact(statement, node.view, defaultSchema), kind: 'view', securityInvoker, node });
+}
+
+function addSchemaMoveFacts(statement, node, facts, defaultSchema) {
+  if (!node.relation) return;
+  const item = relationFact(statement, node.relation, defaultSchema);
+  facts.schemaMoves.push({ ...item, fromSchema: item.schema, schema: node.newschema, objtype: node.objectType });
+}
+
+function addRoleFacts(statement, node, facts) {
+  const kind = statement.type === 'CreateRoleStmt' ? 'create' : 'alter';
+  const name = typeof node.role === 'string' ? node.role : node.role?.rolename;
+  facts.roles.push({ kind, name, options: node.options ?? [], node, index: statement.index, line: statement.line });
+}
+
+function addDropRoleFacts(statement, node, facts) {
+  for (const role of node.roles ?? []) facts.roles.push({ kind: 'drop', name: roleOf(role), options: [], node, index: statement.index, line: statement.line });
+}
+
+function addRoleGrantFacts(statement, node, facts) {
+  facts.roleGrants.push({ node, index: statement.index, line: statement.line });
+}
+
+function addPublicationFacts(statement, node, facts, defaultSchema) {
+  const tables = (node.pubobjects ?? []).flatMap((object) => {
+    const relation = object?.PublicationObjSpec?.pubtable?.relation;
+    return relation ? [{ schema: schemaOf(relation, defaultSchema), name: relation.relname }] : [];
+  });
+  facts.publications.push({ name: node.pubname, action: node.action, allTables: node.for_all_tables === true, tables, node, index: statement.index, line: statement.line });
+}
+
 function addCreatePolicyFacts(statement, node, facts, defaultSchema) {
   const policy = {
     name: node.policy_name,
@@ -104,6 +155,7 @@ function addAlterPolicyFacts(statement, node, facts, defaultSchema) {
     ...(node.qual !== undefined ? { qual: node.qual } : {}),
     ...(node.with_check !== undefined ? { withCheck: node.with_check } : {}),
     index: statement.index,
+    line: statement.line,
   });
 }
 
@@ -123,6 +175,7 @@ function addGrantFacts(statement, node, facts, defaultSchema) {
     objtype: node.objtype,
     objects: node.objects ?? [],
     privileges: (node.privileges ?? []).map((privilege) => String(privilege?.AccessPriv?.priv_name ?? '').toLowerCase()),
+    all: (node.privileges ?? []).length === 0,
     grantees: (node.grantees ?? []).map(roleOf),
     defaultSchema,
     index: statement.index,
@@ -130,13 +183,17 @@ function addGrantFacts(statement, node, facts, defaultSchema) {
   });
 }
 
-function addDefaultPrivilegeFacts(statement, node, facts) {
+function addDefaultPrivilegeFacts(statement, node, facts, defaultSchema) {
   const action = node.action ?? {};
+  const schemas = (node.options ?? []).find((option) => option?.DefElem?.defname === 'schemas')?.DefElem?.arg?.List?.items;
   facts.defaultPrivileges.push({
     grant: action.is_grant === true,
     objtype: action.objtype,
     privileges: (action.privileges ?? []).map((privilege) => String(privilege?.AccessPriv?.priv_name ?? '').toLowerCase()),
+    all: (action.privileges ?? []).length === 0,
     grantees: (action.grantees ?? []).map(roleOf),
+    schemas: (schemas ?? []).map(sval).filter(Boolean),
+    defaultSchema,
     index: statement.index,
     line: statement.line,
   });
@@ -151,7 +208,8 @@ function addCreateFunctionFacts(statement, node, facts, defaultSchema) {
 function addAlterFunctionFacts(statement, node, facts, defaultSchema) {
   const rawName = nameOf(node.func?.objname);
   const name = rawName.includes('.') ? rawName : `${defaultSchema}.${rawName}`;
-  facts.alterFunctions.push({ name, setsPath: (node.actions ?? []).some((action) => isSearchPathSet(action?.DefElem)), index: statement.index, line: statement.line });
+  const securityDefiner = (node.actions ?? []).some((action) => action?.DefElem?.defname === 'security' && action?.DefElem?.arg?.Boolean?.boolval === true);
+  facts.alterFunctions.push({ name, schema: name.split('.')[0], node, securityDefiner, setsPath: (node.actions ?? []).some((action) => isSearchPathSet(action?.DefElem)), index: statement.index, line: statement.line });
 }
 
 function addDoBlockFacts(statement, node, facts) {
@@ -173,6 +231,9 @@ function addBucketCallFacts(statement, node, facts) {
 const statementFactHandlers = new Map([
   ['VariableSetStmt', (statement, node, facts, defaultSchema) => searchPathSchema(node, defaultSchema)],
   ['CreateStmt', addTableFacts], ['CreateTableAsStmt', addTableFacts], ['AlterTableStmt', addAlterTableFacts],
+  ['ViewStmt', addViewFacts], ['AlterObjectSchemaStmt', addSchemaMoveFacts],
+  ['CreateRoleStmt', addRoleFacts], ['AlterRoleStmt', addRoleFacts], ['DropRoleStmt', addDropRoleFacts],
+  ['GrantRoleStmt', addRoleGrantFacts], ['CreatePublicationStmt', addPublicationFacts], ['AlterPublicationStmt', addPublicationFacts],
   ['CreatePolicyStmt', addCreatePolicyFacts], ['AlterPolicyStmt', addAlterPolicyFacts], ['DropStmt', addDropPolicyFacts],
   ['GrantStmt', addGrantFacts], ['AlterDefaultPrivilegesStmt', addDefaultPrivilegeFacts], ['CreateFunctionStmt', addCreateFunctionFacts],
   ['AlterFunctionStmt', addAlterFunctionFacts], ['DoStmt', addDoBlockFacts], ['InsertStmt', addBucketInsertFacts], ['SelectStmt', addBucketCallFacts],
@@ -183,9 +244,11 @@ function factsOf(statements) {
   const facts = {
     tables: [], enables: [], forces: [], policies: [], policyEvents: [], grants: [], defaultPrivileges: [],
     functions: [], alterFunctions: [], doBlocks: [], buckets: [], bucketCalls: [], isSearchPathSet,
+    statements: [], views: [], rlsEvents: [], owners: [], schemaMoves: [], roles: [], roleGrants: [], publications: [],
   };
   let defaultSchema = 'public';
   for (const statement of statements) {
+    facts.statements.push({ ...statement, defaultSchema });
     const { node } = statement;
     const handler = statementFactHandlers.get(statement.type);
     if (handler) defaultSchema = handler(statement, node, facts, defaultSchema) ?? defaultSchema;
@@ -193,18 +256,37 @@ function factsOf(statements) {
   return facts;
 }
 
+function relationHasLaterEvent(events, table) {
+  return events.some((event) => event.schema === table.schema && event.name === table.name && event.index > table.index);
+}
+
+function rlsWeakeningFindings(file, events, exposed) {
+  const findings = [];
+  for (const event of events) {
+    if (!exposed.has(event.schema) || (event.enabled !== false && event.forced !== false)) continue;
+    const qualified = `${event.schema}.${event.name}`;
+    const operation = event.enabled === false ? 'disables row level security' : 'removes forced row level security';
+    findings.push(found(DB_RLS_REQUIRED, file, `${file}:${event.line} ${operation} on ${qualified} in the exposed schema ${event.schema}`, { line: event.line, table: qualified }));
+  }
+  return findings;
+}
+
 function rlsFindings(file, facts, exposed, forceRls) {
+  const movedTables = facts.schemaMoves.filter((move) => move.objtype === 'OBJECT_TABLE').map((move) => ({ ...move, moved: true }));
+  const targets = [...facts.tables, ...movedTables];
   const findings = [];
-  for (const table of facts.tables) {
+  for (const table of targets) {
     if (!exposed.has(table.schema)) continue;
     const qualified = `${table.schema}.${table.name}`;
-    if (!facts.enables.some((enable) => enable.schema === table.schema && enable.name === table.name && enable.index > table.index)) {
-      findings.push(found(DB_RLS_REQUIRED, file, `${file}:${table.line} creates ${qualified} in the exposed schema ${table.schema} without a later \`alter table ${qualified} enable row level security\` in the same migration`, { line: table.line, table: qualified }));
+    const operation = table.moved ? 'moves' : 'creates';
+    if (!relationHasLaterEvent(facts.enables, table)) {
+      findings.push(found(DB_RLS_REQUIRED, file, `${file}:${table.line} ${operation} ${qualified} into the exposed schema ${table.schema} without a later \`alter table ${qualified} enable row level security\` in the same migration`, { line: table.line, table: qualified }));
     }
-    if (forceRls.has(qualified) && !facts.forces.some((force) => force.schema === table.schema && force.name === table.name && force.index > table.index)) {
-      findings.push(found(DB_RLS_REQUIRED, file, `${file}:${table.line} creates ${qualified}, which hfs.json supabase.forceRls declares definer-owned, without \`alter table ${qualified} force row level security\` in the same migration`, { line: table.line, table: qualified }));
+    if (forceRls.has(qualified) && !relationHasLaterEvent(facts.forces, table)) {
+      findings.push(found(DB_RLS_REQUIRED, file, `${file}:${table.line} ${operation} ${qualified}, which hfs.json supabase.forceRls declares definer-owned, without \`alter table ${qualified} force row level security\` in the same migration`, { line: table.line, table: qualified }));
     }
   }
+  findings.push(...rlsWeakeningFindings(file, facts.rlsEvents, exposed));
   return findings;
 }
 

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

@@ -4,11 +4,18 @@ import { found, readJson, readText } from './read.mjs';
 import { configFindings, parseToml, typesFindings } from './database-config.mjs';
 import { defaultGit, migrationShapeFindings } from './database-migrations.mjs';
 import { migrationSetPolicyFindings, sqlAnalysis } from './database-sql.mjs';
+import { migrationSetDefinerFindings } from './database-plpgsql.mjs';
+import { databaseAccessFindings } from './database-access.mjs';
 import { CONFIG_FILE, DB_CONFIG_POLICY, DB_MIGRATION_SHAPE, isActiveMigration, MIGRATIONS_ARCHIVE_DIR, TYPES_FILE } from './database-constants.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 import { eachInOrder } from '../../lib/in-order.mjs';
 
 export { migrationStamp } from './database-migrations.mjs';
+export {
+  DB_BE_ONLY_ACCESS, DB_REALTIME_UNLISTED, DB_APP_ROLE, DB_FORCE_RLS_DEFAULT,
+  DB_POLICY_TAUTOLOGY, DB_VIEW_UNSAFE, DB_STORAGE_PREFIX,
+} from './database-access.mjs';
+export const DB_DEFINER_REVOKE = 'DB_DEFINER_REVOKE';
 export {
   CONFIG_FILE,
   DB_CONFIG_POLICY,
@@ -51,7 +58,7 @@ async function migrationAnalyses({ repoRoot, migrations, exposed, forceRls, find
  * starts neither Docker nor the Supabase CLI. A full app is judged when it declares a Supabase connection, while
  * lite apps are judged even before their initial Supabase files have all been scaffolded.
  */
-export async function checkDatabase({ repoRoot, files, base, git, edition, supabase, emitTypes, now = () => Date.now() } = {}) {
+export async function checkDatabase({ repoRoot, files, base, git, edition, supabase, emitTypes } = {}) {
   const findings = [];
   const migrations = files.filter(isActiveMigration).sort(byCodeUnit);
   const archived = files.filter((file) => file.startsWith(`${MIGRATIONS_ARCHIVE_DIR}/`));
@@ -71,11 +78,13 @@ export async function checkDatabase({ repoRoot, files, base, git, edition, supab
   const apiSchemas = (config?.api?.schemas ?? []).filter((schema) => typeof schema === 'string');
   const exposed = new Set(['public', ...apiSchemas]);
   const forceRls = new Set((declared?.forceRls ?? []).map((name) => (name.includes('.') ? name : `public.${name}`)));
-  findings.push(...await migrationShapeFindings({ repoRoot, migrations, archived, git: git ?? defaultGit, base, now }));
+  findings.push(...await migrationShapeFindings({ repoRoot, migrations, archived, git: git ?? defaultGit, base }));
 
   const analyses = await migrationAnalyses({ repoRoot, migrations, exposed, forceRls, findings });
   findings.push(
     ...migrationSetPolicyFindings(analyses),
+    ...migrationSetDefinerFindings(analyses, exposed),
+    ...await databaseAccessFindings({ analyses, exposed, supabase: declared }),
     ...await typesFindings({ repoRoot, files, emitTypes, declaration: declared }),
   );
   return findings;

package/runtime/scripts/hfs/rules/deploy-scan.mjs

@@ -0,0 +1,192 @@
+// R250: host scheduling and application logic do not belong in deployment sources; compose mutations stay in dev.
+import { parseWorkflow } from '../runtime-rules/workflow-source.mjs';
+import { words } from '../../lib/dockerfile.mjs';
+import { found, readText } from './read.mjs';
+
+const WORKFLOW = /(?:^|\/)\.github\/workflows\/[^/]+\.ya?ml$/;
+const DEPLOY = /(?:^|\/)deploy\//;
+const SCRIPT = /(?:^|\/)scripts\//;
+const COMPOSE = /(?:^|\/)(?:docker-)?compose(?:[.-][^/]*)?\.ya?ml$/;
+const DOCKERFILE = /(?:^|\/)Dockerfile(?:\.[^/]*)?$/;
+const CREDENTIAL_FILE = /(?:^|\/)(?:secrets?\.env(?:\.[^/]*)?|\.env(?:\.[^/]*)?|secrets\/)|\.enc$/i;
+const HOST_CRON = /\b(?:crontab|anacron|crond|supercronic)\b|\/etc\/cron(?:\b|[./])|\bcron\.d\b|\/var\/spool\/cron\b|@(?:reboot|yearly|annually|monthly|weekly|daily|midnight|hourly)\b|\b[\w.@-]+\.timer\b|\bOn(?:Calendar|BootSec|UnitActiveSec|ActiveSec)\s*=|(?:^|[\s;|&"'])at\s+(?:(?:-[a-z]+\s+)*)((?:-[ft]\b)|now\b|tomorrow\b|\d{1,2}:\d{2}\b|midnight\b|noon\b)/im;
+const HOST_CRON_PATH = /(?:^|\/)(?:crontab(?:$|\/)|cron\.d(?:\/|$)|[^/]+\.(?:timer|crontab)$)/;
+const CRON_NUMERIC_FIELD = /^[\d*,/-]+$/;
+const CRON_NAMED_FIELD = /^[\w*,/-]+$/;
+const CRON_CONTAINER = /\bimage\s*:\s*["']?(?:[^\s"']*\/)?(?:cron|crond|supercronic|ofelia)(?=[:@\s"']|$)|\b(?:command|entrypoint)\s*:[^\n]*\b(?:cron|crond|supercronic)\b/i;
+const SLEEP_LOOP = /\b(?:while\s+(?:true|:|\[\s*1\s*\])|for\s*\(\(\s*;\s*;\s*\)\))\s*[;\n][\s\S]{0,4000}?\bsleep\s+/i;
+const INLINE_NODE = /\bnode\b[^\n;&|]*?\s(?:-(?:e|p|pe)\b|--(?:eval|print)(?:\s|=))/;
+const INLINE_SQL_ACTION = /\b(?:insert\s+into|update\s+[\w."']+\s+set|delete\s+from|create\s+(?:table|function|view)|alter\s+table|truncate\s+(?:table\s+)?[\w."'])\b/i;
+const REMOTE_SHELL = /\b(?:curl|wget)\b[^|\n]*\|\s*(?:sudo\s+)?(?:ba|da|z)?sh\b/i;
+const COMPOSE_COMMAND = /\bdocker(?:\s+(?:--(?:context|host)(?:\s+|=)\S+|-H\s+\S+))*\s+compose\b[^\n;&|]*|\bdocker-compose\b[^\n;&|]*/g;
+const COMPOSE_OPTIONS = new Set(['-f', '--file', '-p', '--project-name', '--project-directory', '--env-file', '--profile', '--parallel', '--ansi', '--progress']);
+const DEV = /(?:^|[\s/._="'-])(?:dev|development|local)(?=$|[\s/._"'-])/i;
+const NON_DEV = /(?:^|[\s/._="'-])(?:prod|production|staging|stage|vps|preview)(?=$|[\s/._"'-])/i;
+const WORKFLOW_ENV_NAMES = ['DEPLOY_ENV', 'NODE_ENV', 'ENVIRONMENT', 'STARCI_ENV'];
+
+/** Comments carry no executable scheduling; preserve strings so embedded SSH commands remain visible. */
+function sourceText(text) {
+  return text.split('\n').map((line) => {
+    const trimmed = line.trimStart();
+    return trimmed.startsWith('#') || trimmed.startsWith('//') ? '' : line;
+  }).join('\n').replaceAll(/\\\r?\n\s*/g, ' ');
+}
+
+function cronTable(text) {
+  return text.split('\n').some((line) => {
+    const fields = line.trimStart().replace(/^["']/, '').trimEnd().split(/\s+/);
+    return fields.length >= 6
+      && fields.slice(0, 3).every((field) => CRON_NUMERIC_FIELD.test(field))
+      && fields.slice(3, 5).every((field) => CRON_NAMED_FIELD.test(field));
+  });
+}
+
+function firstWordOffsets(text) {
+  const offsets = new Set();
+  let offset = 0;
+  for (const line of text.split(/[\r\n\u2028\u2029]/)) {
+    offsets.add(offset + line.length - line.trimStart().length);
+    offset += line.length + 1;
+  }
+  return offsets;
+}
+
+function inlineSql(text) {
+  if (INLINE_SQL_ACTION.test(text)) return true;
+  const offsets = firstWordOffsets(text);
+  for (const match of text.matchAll(/select/gi)) {
+    const preceding = text[match.index - 1];
+    const startsSql = offsets.has(match.index) || preceding === '"' || preceding === "'";
+    if (startsSql && /^\s+[^\n;]/.test(text.slice(match.index + match[0].length))) return true;
+  }
+  return false;
+}
+
+function deploymentSource(file) {
+  if (CREDENTIAL_FILE.test(file) || /\.(?:md|png|jpe?g|svg|pdf|zip|gz)$/i.test(file)) return false;
+  return DEPLOY.test(file) || SCRIPT.test(file) || WORKFLOW.test(file) || COMPOSE.test(file) || DOCKERFILE.test(file);
+}
+
+function stackEnvironments(text) {
+  return [...text.matchAll(/\.starcistacks\/([^/\s"']+)\//g)].map((match) => match[1]);
+}
+
+function composeTargets(command) {
+  const parts = words(command);
+  const targets = [];
+  for (let i = 0; i < parts.length; i += 1) {
+    if (['-f', '--file', '--env-file', '--project-directory'].includes(parts[i])) {
+      i += 1;
+      targets.push(parts[i] ?? '');
+    }
+    else if (/^--(?:file|env-file|project-directory)=/.test(parts[i])) targets.push(parts[i].slice(parts[i].indexOf('=') + 1));
+    else if (/^-f.+/.test(parts[i])) targets.push(parts[i].slice(2));
+  }
+  return targets;
+}
+
+function targetsNonDev(command, { environment, directory, remote }) {
+  if (remote || /--context(?:=|\s+)(?:prod(?:uction)?|staging|vps)\b|--host(?:=|\s+)ssh:\/\//i.test(command)) return true;
+  const targets = composeTargets(command);
+  if (targets.length) return targets.some((target) => {
+    const environments = stackEnvironments(target);
+    return environments.length ? environments.some((name) => !/^(?:dev|development|local)$/i.test(name)) : !DEV.test(target) || NON_DEV.test(target);
+  });
+  if (NON_DEV.test(environment) || NON_DEV.test(directory)) return true;
+  if (DEV.test(environment) || DEV.test(directory)) return false;
+  return true;
+}
+
+function composeMutation(command) {
+  const parts = words(command);
+  const composeAt = parts.findIndex((part) => part === 'compose' || part === 'docker-compose');
+  const arguments_ = parts.slice(composeAt + 1);
+  for (let i = 0; i < arguments_.length; i += 1) {
+    const argument = arguments_[i];
+    if (COMPOSE_OPTIONS.has(argument)) { i += 1; continue; }
+    if (argument.startsWith('-')) continue;
+    return ['up', 'down', 'pull'].includes(argument);
+  }
+  return false;
+}
+
+/** Job-local context prevents a production job from changing how a separate dev compose step is judged. */
+function workflowCommands(doc) {
+  const entries = [];
+  for (const job of Object.values(doc?.jobs ?? {})) {
+    const environment = typeof job?.environment === 'string' ? job.environment : job?.environment?.name ?? '';
+    const environmentNames = WORKFLOW_ENV_NAMES.map((key) => job?.env?.[key] ?? doc?.env?.[key] ?? '').join(' ');
+    const context = { environment: `${environment} ${environmentNames}` };
+    for (const step of Array.isArray(job?.steps) ? job.steps : []) {
+      const directory = step?.['working-directory'] ?? job?.defaults?.run?.['working-directory'] ?? doc?.defaults?.run?.['working-directory'] ?? '';
+      const stepEnvironments = WORKFLOW_ENV_NAMES.map((key) => step?.env?.[key] ?? '').join(' ');
+      for (const source of [step?.run, step?.with?.script]) {
+        if (typeof source === 'string') entries.push({ source: sourceText(source), context: { ...context, environment: `${context.environment} ${stepEnvironments}`, directory, remote: Boolean(step?.with?.host && !/^(?:localhost|127\.0\.0\.1)$/.test(step.with.host)) } });
+      }
+    }
+  }
+  return entries;
+}
+
+function composeOnVps(file, text, doc) {
+  let entries = doc ? workflowCommands(doc) : [{ source: text, context: { environment: '', directory: '' } }];
+  if (file.endsWith('/package.json')) {
+    try { entries = Object.values(JSON.parse(text)?.scripts ?? {}).filter((command) => typeof command === 'string').map((source) => ({ source, context: { environment: '', directory: '' } })); } catch { /* Invalid JSON is judged by its own rule. */ }
+  }
+  return entries.some(({ source, context }) => [...source.matchAll(COMPOSE_COMMAND)].some((match) => {
+    const before = source.slice(0, match.index);
+    const linePrefix = before.slice(before.lastIndexOf('\n') + 1);
+    const directory = workingDirectory(before) ?? context.directory;
+    const remote = context.remote || (/\bssh\b/.test(linePrefix) && !/\b(?:localhost|127\.0\.0\.1)\b/.test(linePrefix));
+    return composeMutation(match[0]) && targetsNonDev(match[0], { ...context, directory, remote });
+  }));
+}
+
+function workingDirectory(source) {
+  let directory;
+  for (const command of source.split(/[\n;&]/)) {
+    const match = /^cd\s+([\w./-]+)/.exec(command.trimStart());
+    if (match) directory = match[1];
+  }
+  return directory;
+}
+
+function workflowSchedule(doc, text) {
+  return Boolean(doc?.on && typeof doc.on === 'object' && Object.hasOwn(doc.on, 'schedule'))
+    || (!doc && text.split('\n').some((line) => /^schedule\s*:/.test(line.trimStart())));
+}
+
+function deploymentLogic(file, text) {
+  return DEPLOY.test(file) && /\.(?:sh|bash)$/.test(file)
+    && (INLINE_NODE.test(text) || /\bpsql\b/.test(text) || inlineSql(text) || REMOTE_SHELL.test(text));
+}
+
+function sourceFindings(file, text, doc) {
+  const findings = [];
+  const cronContainer = CRON_CONTAINER.test(text);
+  const host = HOST_CRON.test(text) || HOST_CRON_PATH.test(file) || cronTable(text) || cronContainer || /\b(?:service\s+cron|cron\s+-[a-z]|cron\s*$)/im.test(text);
+  if (host) findings.push(found('HFS_HOST_CRON', file, 'Host cron, systemd timers and at jobs are forbidden; use an app-owned scheduler or a declared replicated-job'));
+  if ((WORKFLOW.test(file) && workflowSchedule(doc, text)) || (DEPLOY.test(file) && host) || cronContainer || SLEEP_LOOP.test(text)) {
+    findings.push(found('HFS_DEPLOY_SCHEDULER', file, 'Deployment sources must not own recurring schedules; move scheduled work into the app and declare its job'));
+  }
+  if (deploymentLogic(file, text)) {
+    findings.push(found('HFS_DEPLOY_NO_LOGIC', file, 'Deployment shell scripts must delegate to docker, starci or the built cli app; move inline application or database logic into the cli app'));
+  }
+  if (composeOnVps(file, text, doc)) findings.push(found('HFS_DEPLOY_COMPOSE_ON_VPS', file, 'Compose up, down and pull are dev-only; deploy a non-dev environment through its declared Swarm or Kubernetes runtime'));
+  return findings;
+}
+
+/** Findings are names and paths only: deployment source snippets and credential values are never reported. */
+export function deployScanFindings({ repoRoot, files, all, repo, isRoot, inScope = () => true }) {
+  if (repo?.kind !== 'app' || !['lite', 'full'].includes(repo.edition) || isRoot === false) return [];
+  const findings = [];
+  for (const file of new Set(all ?? files)) {
+    if (!inScope(file) || !deploymentSource(file)) continue;
+    const raw = readText(repoRoot, file);
+    if (raw === null) continue;
+    const text = sourceText(raw);
+    const doc = WORKFLOW.test(file) ? parseWorkflow(raw) : null;
+    findings.push(...sourceFindings(file, text, doc));
+  }
+  return findings;
+}

package/runtime/scripts/hfs/rules/deploy-workflow.mjs

@@ -0,0 +1,219 @@
+// R251: product workflow custody, immutable dependencies and release-only triggers, in both editions.
+import { parseWorkflow, workflowFindings } from '../runtime-rules/workflow-source.mjs';
+import { found, readText } from './read.mjs';
+import { isPlainObject as record } from '../../../engine/plain-object.mjs';
+import { workflowEventOptions } from '../../lib/workflow-events.mjs';
+
+const DEPLOY = 'HFS_DEPLOY_WORKFLOW';
+const PIN = 'HFS_WORKFLOW_PIN';
+const TOOL = 'HFS_CI_TOOL_INSTALL';
+const TRIGGER = 'HFS_APP_WORKFLOW_TRIGGER';
+// Only the age identity and SSH transport credentials belong in the CI secret store.
+const CI_SECRET_ENV_NAMES = new Set(['SOPS_AGE_KEY', 'SSH_KEY', 'SSH_PRIVATE_KEY', 'SSH_KNOWN_HOSTS', 'VPS_SSH_KEY', 'VPS_SSH_PRIVATE_KEY', 'VPS_KNOWN_HOSTS', 'VPS_SSH_KNOWN_HOSTS', 'DEPLOY_SSH_KEY', 'DEPLOY_SSH_PRIVATE_KEY', 'DEPLOY_KNOWN_HOSTS', 'DEPLOY_SSH_KNOWN_HOSTS']);
+const nonempty = (value) => typeof value === 'string' && value.trim().length > 0;
+function executable(script) {
+  let result = '';
+  let quote = '';
+  for (let index = 0; index < script.length; index++) {
+    const character = script[index];
+    if (character === '\\' && quote !== "'") { result += character + (script[++index] ?? ''); continue; }
+    if (!quote && character === '#' && (index === 0 || /[\s;&|()]/.test(script[index - 1]))) {
+      while (index < script.length && script[index] !== '\n') index++;
+      result += '\n';
+      continue;
+    }
+    if (character === quote) quote = '';
+    else if (!quote && (character === "'" || character === '"')) quote = character;
+    result += character;
+  }
+  return result.replace(/\\\r?\n/g, ' ');
+}
+
+function commands(script) {
+  const result = [];
+  let quote = '';
+  let start = 0;
+  for (let index = 0; index < script.length; index++) {
+    const character = script[index];
+    if (character === '\\' && quote !== "'") { index++; continue; }
+    if (character === quote) quote = '';
+    else if (!quote && (character === "'" || character === '"')) quote = character;
+    else if (!quote && /[\n;&|]/.test(character)) { result.push({ text: script.slice(start, index).trim(), start, end: index, separator: character }); start = index + 1; }
+  }
+  result.push({ text: script.slice(start).trim(), start });
+  return result.filter((command) => command.text);
+}
+
+const commandBody = (command) => command.replace(/^(?:(?:sudo|env)\s+|[A-Za-z_]\w*=[^\s]+\s+)*/, '');
+
+function entries(value) {
+  if (!value || typeof value !== 'object') return [];
+  return Object.entries(value).flatMap(([key, member]) => [{ key, value: member }, ...entries(member)]);
+}
+
+const strings = (value) => entries(value).filter((entry) => typeof entry.value === 'string').map((entry) => entry.value);
+const activeSteps = (job) => (Array.isArray(job.steps) ? job.steps : []).filter((step) => record(step) && step.if !== false && step.if !== 'false' && !/^\$\{\{\s*false\s*\}\}$/.test(String(step.if ?? '')));
+const scripts = (job) => activeSteps(job).flatMap((step) => [step.run, step.with?.script].filter(nonempty).map(executable));
+const validEnvironment = (value) => nonempty(value) || (record(value) && nonempty(value.name));
+const validPermissions = (value) => record(value) || value === 'read-all' || value === 'write-all';
+const validConcurrency = (value) => nonempty(value) || (record(value) && nonempty(value.group));
+const deployName = (value) => !/authorize[\s_.-]+deploy[\s_.-]+key/i.test(value) && /(?:^|[\s/_.-])deploy(?:[\s/_.-]|$)/i.test(value);
+const materializeCommand = (script) => commands(script).some(({ text }) => /^starci\s+app\s+secret\s+materialize\b/.test(commandBody(text)));
+const deploymentCommand = (script) => commands(script).some(({ text }) => /^(?:starci\s+(?:app\s+)?(?:deploy|secret\s+materialize)\b|docker\s+stack\s+deploy\b|(?:ba?sh\s+)?(?:\.\/)?deploy\/|(?:ba?sh\s+)?(?:\.\/)?(?:scripts\/)?[\w.-]*deploy[\w.-]*\.sh\b|npm\s+run\s+deploy(?=[:\s]|$))/.test(commandBody(text)));
+
+function hasAgeIdentity(job, doc) {
+  const steps = activeSteps(job);
+  if ([doc.env, job.env, ...steps.map((step) => step.env)].some((env) => record(env) && nonempty(env.SOPS_AGE_KEY))) return true;
+  const reference = /\$\{\{\s*secrets\s*(?:\.\s*SOPS_AGE_KEY|\[\s*(['"])SOPS_AGE_KEY\1\s*\])/;
+  return steps.some((step) => strings(step.with).some((value) => reference.test(value)) || (typeof step.run === 'string' && reference.test(executable(step.run))));
+}
+
+function triggerFindings(doc, refuse) {
+  const on = workflowEventOptions(doc.on);
+  if (!record(on) || !Object.keys(on).length) return [refuse(TRIGGER, 'declare release tags [v*] and/or workflow_dispatch')];
+  const findings = [];
+  for (const [event, options] of Object.entries(on)) {
+    if (event === 'workflow_dispatch') continue;
+    if (event !== 'push') {
+      findings.push(refuse(TRIGGER, `trigger ${event} is forbidden; app CI starts only on release tags [v*] or workflow_dispatch`));
+      continue;
+    }
+    if (!record(options) || !Array.isArray(options.tags) || options.tags.length !== 1 || options.tags[0] !== 'v*' || Object.keys(options).some((key) => key !== 'tags')) {
+      findings.push(refuse(TRIGGER, 'push must contain only tags: [v*]; branch and path filters are forbidden'));
+    }
+  }
+  return findings;
+}
+
+function actionFindings(doc, refuse) {
+  const findings = [];
+  for (const { key, value } of entries(doc)) {
+    if (key !== 'uses') continue;
+    const local = typeof value === 'string' && /^\.\/[\w./-]+$/.test(value);
+    const remote = typeof value === 'string' && /^[\w.-]+\/[\w.-]+(?:\/[\w./-]+)?@[a-f\d]{40}$/i.test(value);
+    const container = typeof value === 'string' && /^docker:\/\/[^\s@]+@sha256:[a-f\d]{64}$/i.test(value);
+    if (!local && !remote && !container) findings.push(refuse(PIN, 'every remote uses entry needs a full 40-hex commit SHA (a container action needs a sha256 digest)'));
+  }
+  return findings;
+}
+
+function secretProblems(doc) {
+  const problems = [];
+  if (entries(doc).some(({ key, value }) => key === 'secrets' && value === 'inherit')) problems.push('inherited secrets are forbidden');
+  for (const value of strings(doc)) {
+    for (const expression of value.matchAll(/\$\{\{([\s\S]*?)\}\}/g)) {
+      const text = expression[1];
+      const refs = [...text.matchAll(/\bsecrets\s*(?:\.\s*([A-Za-z_]\w*)|\[\s*(['"])([^'"]+)\2\s*\])/g)];
+      for (const ref of refs) if (!CI_SECRET_ENV_NAMES.has(ref[1] ?? ref[3])) problems.push('a secrets reference is outside the age-key/SSH transport allowlist');
+      if (/\bsecrets\b/.test(text.replace(/\bsecrets\s*(?:\.\s*[A-Za-z_]\w*|\[\s*(['"])[^'"]+\1\s*\])/g, ''))) problems.push('dynamic or bulk secrets access is forbidden');
+    }
+  }
+  return [...new Set(problems)];
+}
+
+function dotenvTarget(script, start) {
+  let index = start;
+  while (index < script.length && /\s/.test(script[index])) index++;
+  if (script[index] === '"' || script[index] === "'") index++;
+  const from = index;
+  while (index < script.length && !/[\s"';|<>]/.test(script[index])) index++;
+  if (index < script.length && !/[\s"';|]/.test(script[index])) return false;
+  const target = script.slice(from, index);
+  const name = target.slice(target.lastIndexOf('/') + 1);
+  if (name.startsWith('.env')) return /^[.\w-]*$/.test(name.slice(4));
+  return name.endsWith('.env') && /^[\w.-]+$/.test(name.slice(0, -4));
+}
+
+function scriptWritesDotenv(value) {
+  const script = executable(value);
+  for (const match of script.matchAll(/>{1,2}|\btee\s+(?:-a\s+)?/g)) {
+    if (dotenvTarget(script, match.index + match[0].length)) return true;
+  }
+  return false;
+}
+
+function writesDotenv(doc) {
+  return entries(doc).some(({ key, value }) => key === 'env_file' || key === 'env-file' || (['run', 'script'].includes(key) && typeof value === 'string' && scriptWritesDotenv(value)));
+}
+
+function deploymentJobs(doc, file) {
+  const jobs = record(doc.jobs) ? Object.entries(doc.jobs).filter(([, job]) => record(job)) : [];
+  const identified = jobs.filter(([name, job]) => deployName(name) || deployName(String(job.name ?? '')) || scripts(job).some(deploymentCommand) || (typeof job.uses === 'string' && deployName(job.uses)));
+  if (identified.length) return identified;
+  if (deployName(file) || deployName(String(doc.name ?? ''))) return jobs;
+  return [];
+}
+
+function deploymentJobFindings(name, job, doc, refuse) {
+  const findings = [];
+  if (!validEnvironment(job.environment)) findings.push(refuse(DEPLOY, `job ${name} must declare its protected environment`));
+  if (!validPermissions(job.permissions ?? doc.permissions)) findings.push(refuse(DEPLOY, `job ${name} must declare permissions at job or workflow scope`));
+  if (!validConcurrency(job.concurrency ?? doc.concurrency)) findings.push(refuse(DEPLOY, `job ${name} must declare concurrency at job or workflow scope`));
+  if (!hasAgeIdentity(job, doc) && !scripts(job).some(materializeCommand)) findings.push(refuse(DEPLOY, `job ${name} must inject SOPS_AGE_KEY or run starci app secret materialize`));
+  return findings;
+}
+
+function deploymentFindings(doc, file, refuse) {
+  const deployment = deploymentJobs(doc, file);
+  const named = deployName(file) || deployName(String(doc.name ?? ''));
+  if (!deployment.length && !named) return [];
+  const findings = [];
+  if (!deployment.length) findings.push(refuse(DEPLOY, 'the deploy workflow must declare a deployment job'));
+  for (const [name, job] of deployment) findings.push(...deploymentJobFindings(name, job, doc, refuse));
+  for (const problem of secretProblems(doc)) findings.push(refuse(DEPLOY, problem));
+  if (writesDotenv(doc)) findings.push(refuse(DEPLOY, 'deploy workflows must never write dotenv files or use env_file blobs; materialize sealed custody'));
+  return findings;
+}
+
+// A version label alone is not an integrity pin. The immutable reference or verified artifact must belong to this install.
+function verifiedArtifact(artifact, prior) {
+  if (!/^\.\/[\w./-]+\.(?:tgz|tar\.gz|whl)$/.test(artifact)) return false;
+  return prior.split(/\r?\n/).some((line) => {
+    const checksum = line.trim().match(/^echo\s+(['"])([a-f\d]{64})\s+\*?(\S+)\1\s*\|\s*sha256sum\s+(?:--check|-c)\s+-\s*(?:$|&&)/i);
+    return checksum && checksum[3].replace(/^\.\//, '') === artifact.slice(2) && !line.includes('||');
+  });
+}
+
+function pinnedInstall(command, prior) {
+  if (/^(?:python(?:3)?\s+-m\s+)?pip(?:3)?\s+install\b/.test(command)) {
+    // pip's hash-checking mode refuses every unhashed direct or transitive requirement itself.
+    if (/(?:^|\s)--require-hashes(?:\s|$)/.test(command)) return true;
+    const targets = command.replace(/^(?:python(?:3)?\s+-m\s+)?pip(?:3)?\s+install\s*/, '').split(/\s+/).filter((token) => !token.startsWith('-'));
+    return targets.length > 0 && targets.every((target) => /^git\+https:\/\/\S+@[a-f\d]{40}$/i.test(target) || verifiedArtifact(target, prior));
+  }
+  if (/^go\s+install\b/.test(command)) {
+    const targets = command.replace(/^go\s+install\s*/, '').split(/\s+/).filter((token) => !token.startsWith('-'));
+    return targets.length > 0 && targets.every((target) => /^[\w./-]+@[a-f\d]{40}$/i.test(target));
+  }
+  const targets = command.replace(/^npm\s+(?:(?:-g|--global|--location=global)\s+)*(?:i|install)\s*/, '').split(/\s+/).filter((token) => !token.startsWith('-')).map((token) => token.replace(/^["']|["']$/g, ''));
+  return targets.length > 0 && targets.every((target) => /^git\+https:\/\/\S+#[a-f\d]{40}$/i.test(target) || verifiedArtifact(target, prior));
+}
+
+function toolFindings(doc, refuse) {
+  const findings = [];
+  for (const { key, value } of entries(doc)) {
+    if (!['run', 'script'].includes(key) || typeof value !== 'string') continue;
+    const script = executable(value);
+    const statements = commands(script);
+    if (statements.some((command, index) => /^\b(?:curl|wget)\b/.test(commandBody(command.text)) && command.separator === '|' && /^(?:ba)?sh\b/.test(commandBody(statements[index + 1]?.text ?? '')) || /^(?:ba)?sh\s+<\(\s*(?:curl|wget)\b/.test(commandBody(command.text)))) findings.push(refuse(TOOL, 'a downloaded installer must be checksum-verified before execution; curl/wget piped to a shell is forbidden'));
+    for (const command of statements) {
+      const body = commandBody(command.text);
+      const install = /^(?:go\s+install|(?:python(?:3)?\s+-m\s+)?pip(?:3)?\s+install)\b/.test(body) || /^npm\s+(?:(?:-g|--global|--location=global)\s+)*(?:i|install)\b/.test(body) && /(?:^|\s)(?:-g|--global|--location=global)(?:\s|$)/.test(body);
+      if (install && !pinnedInstall(body, script.slice(0, command.start))) findings.push(refuse(TOOL, 'tool installs need an immutable hash or a verified artifact; use a SHA-pinned setup action instead of a version-only install'));
+    }
+  }
+  return findings;
+}
+
+function perWorkflow({ path: file, text }) {
+  const refuse = (code, message) => found(code, file, `${code} ${file}: ${message}`);
+  const doc = parseWorkflow(text);
+  if (!record(doc)) return [refuse(TRIGGER, 'the workflow must be valid YAML with a release-only on block'), ...(deployName(file) ? [refuse(DEPLOY, 'the deploy workflow must be valid YAML')] : [])];
+  return [...triggerFindings(doc, refuse), ...actionFindings(doc, refuse), ...deploymentFindings(doc, file, refuse), ...toolFindings(doc, refuse)];
+}
+
+/** Synchronous R251 findings over the tracked workflows of a lite/full app. */
+export function deployWorkflowFindings({ repoRoot, files, all = files, repo, isRoot, inScope = () => true }) {
+  if (isRoot === false || repo?.kind !== 'app' || !['lite', 'full'].includes(repo.edition)) return [];
+  return workflowFindings({ files: all.filter((file) => inScope(file)), read: (file) => readText(repoRoot, file) }, perWorkflow);
+}