@starci/hfs 4.11.0 → 4.11.11

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

@@ -0,0 +1,45 @@
+// R213 DB_MIGRATION_SHAPE, transaction control: `starci app db migrate` and the squash replay apply each migration in ONE transaction
+// together with its history row (db/postgres.mjs psqlTransaction, `psql -1`), so a migration never opens, ends or splits a transaction.
+// Top-level BEGIN, START TRANSACTION, COMMIT, END, ROLLBACK, ABORT, SAVEPOINT, RELEASE and PREPARE TRANSACTION are findings, and so is a
+// COMMIT or ROLLBACK statement inside a DO block; a function or procedure body (dollar-quoted or not) is never judged.
+import { found } from './read.mjs';
+import { databaseSqlTokens } from './database-migrations.mjs';
+import { DB_MIGRATION_SHAPE } from './database-constants.mjs';
+
+const CONTROL_IN_DO = new Set(['commit', 'rollback']);
+// PL/pgSQL words after which a statement starts.
+const STATEMENT_OPENERS = new Set(['begin', 'then', 'else', 'loop']);
+
+/** The line of the first token of the statement starting at byte `location` (leading blanks and comments skipped). */
+function statementLine(text, location, lineAt) {
+  const rest = Buffer.from(text, 'utf8').subarray(Math.max(location, 0), Math.max(location, 0) + 4096).toString('utf8');
+  const first = databaseSqlTokens(rest)[0];
+  return lineAt(Math.max(location, 0)) + (first ? first.line - 1 : 0);
+}
+
+const doBody = (node) => (node.args ?? []).find((item) => item.DefElem?.defname === 'as')?.DefElem?.arg?.String?.sval ?? '';
+
+/** Transaction control a migration must not carry, one finding per statement with its file:line. */
+export function transactionControlFindings(file, text, stmts, lineAt) {
+  const findings = [];
+  for (const entry of stmts ?? []) {
+    const line = () => statementLine(text, entry.stmt_location ?? 0, lineAt);
+    if (entry.stmt?.TransactionStmt) {
+      const kind = String(entry.stmt.TransactionStmt.kind ?? '').replace(/^TRANS_STMT_/, '').toLowerCase().replaceAll('_', ' ');
+      const at = line();
+      findings.push(found(DB_MIGRATION_SHAPE, file, `${file}:${at} carries transaction control (${kind}); a migration is applied in one transaction with its history row, so it never begins, commits, rolls back or sets a savepoint`, { line: at }));
+      continue;
+    }
+    if (!entry.stmt?.DoStmt) continue;
+    const body = doBody(entry.stmt.DoStmt);
+    const tokens = databaseSqlTokens(body);
+    tokens.forEach((token, index) => {
+      const before = tokens[index - 1];
+      const leads = !before || before.v === ';' || (before.t === 'word' && STATEMENT_OPENERS.has(before.v));
+      if (token.t !== 'word' || !CONTROL_IN_DO.has(token.v) || !leads) return;
+      const inner = line() + token.line - 1;
+      findings.push(found(DB_MIGRATION_SHAPE, file, `${file}:${inner} carries transaction control (${token.v} inside a DO block); a migration is applied in one transaction with its history row`, { line: inner }));
+    });
+  }
+  return findings;
+}

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

@@ -8,7 +8,7 @@ const DEPLOY = /(?:^|\/)deploy\//;
 const SCRIPT = /(?:^|\/)scripts\//;
 const COMPOSE = /(?:^|\/)(?:docker-)?compose(?:[.-][^/]*)?\.ya?ml$/;
 const DOCKERFILE = /(?:^|\/)Dockerfile(?:\.[^/]*)?$/;
-const CREDENTIAL_FILE_PARTS = [/(?:^|\/)secrets?\.env(?:\.[^/]*)?/, /(?:^|\/)\.env(?:\.[^/]*)?/, /(?:^|\/)secrets\//, /\.enc$/];
+const CREDENTIAL_FILE_PARTS = [/(?:^|\/)secrets?\.env(?:\.[^/]*)?/, /(?:^|\/)\.env(?:\.[^/]*)?/, /(?:^|\/)secrets\//, /\.enc(?:\.yaml)?$/];
 const CREDENTIAL_FILE = new RegExp(CREDENTIAL_FILE_PARTS.map((part) => part.source).join('|'), 'i');
 const AT_JOB_ARGUMENT = /-[ft]\b|now\b|tomorrow\b|\d{1,2}:\d{2}\b|midnight\b|noon\b/.source;
 const HOST_CRON_PARTS = [

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

@@ -160,6 +160,24 @@ function deploymentJobFindings(name, job, doc, refuse) {
   return findings;
 }
 
+const AGE_KEY_REFERENCE = /\$\{\{[^}]*\bsecrets\s*(?:\.\s*SOPS_AGE_KEY\b|\[\s*(['"])SOPS_AGE_KEY\1\s*\])/;
+const readsAgeKey = (value) => strings(value).some((text) => AGE_KEY_REFERENCE.test(text));
+
+/**
+ * A job that reads secrets.SOPS_AGE_KEY opens the members of one environment, so it is bound to that GitHub Environment, whose
+ * SOPS_AGE_KEY is the environment's server identity (PROJECT-STACKS-5/7); unbound, it would read a repository secret of that name.
+ * Disabled steps do not count. A deployment job is judged by deploymentJobFindings, which already requires its environment.
+ */
+function ageKeyJobFindings(doc, file, refuse) {
+  const deployment = new Set(deploymentJobs(doc, file).map(([name]) => name));
+  const workflowWide = readsAgeKey(doc.env);
+  const jobs = record(doc.jobs) ? Object.entries(doc.jobs).filter(([, job]) => record(job)) : [];
+  return jobs
+    .filter(([name, job]) => !deployment.has(name) && !validEnvironment(job.environment))
+    .filter(([, job]) => workflowWide || readsAgeKey({ env: job.env, with: job.with, secrets: job.secrets, steps: activeSteps(job).map((step) => ({ env: step.env, with: step.with, run: nonempty(step.run) ? executable(step.run) : undefined })) }))
+    .map(([name]) => refuse(DEPLOY, `job ${name} reads secrets.SOPS_AGE_KEY without an environment; bind it to the GitHub Environment whose members it opens (environment: <env>), which holds that environment's server key`));
+}
+
 function deploymentFindings(doc, file, refuse) {
   const deployment = deploymentJobs(doc, file);
   const named = deployName(file) || deployName(String(doc.name ?? ''));
@@ -216,7 +234,7 @@ 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, file), ...deploymentFindings(doc, file, refuse), ...toolFindings(doc, refuse)];
+  return [...triggerFindings(doc, refuse, file), ...deploymentFindings(doc, file, refuse), ...ageKeyJobFindings(doc, file, refuse), ...toolFindings(doc, refuse)];
 }
 
 /** Synchronous R251 findings over the tracked workflows of a lite/full app. */

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

@@ -95,7 +95,7 @@ function dependencyFindings(rel, pkg, { removed, catalog, declared }) {
     for (const name of Object.keys(deps)) {
       const service = serviceOfClient(catalog, name);
       if (LITE_FORBIDDEN_TEST_INFRA.test(name)) findings.push(found(HFS_EDITION_FORBIDDEN_PRESENT, rel, `${rel} ${section} has ${name}: a lite app runs no test containers, fault proxy or browser journey - its integration specs run against \`supabase start\``, { section, name }));
-      else if (removed.has(name)) findings.push(found(HFS_EDITION_FORBIDDEN_PRESENT, rel, `${rel} ${section} has ${name}: lite runs no self-hosted Kafka - the event bus port is implemented on Supabase (pgmq) or in process`, { section, name }));
+      else if (removed.has(name)) findings.push(found(HFS_EDITION_FORBIDDEN_PRESENT, rel, `${rel} ${section} has ${name}: lite runs no self-hosted Kafka - the event bus port is implemented on pgmq in the db service`, { section, name }));
       else if (service !== null && !judgedInEdition(catalog[service], 'lite')) findings.push(found(HFS_BACKING_UNDECLARED, rel, `${rel} ${section} has ${name}, a client of ${service}, which the lite edition does not admit: remove the dependency`, { section, name, service }));
       else if (service !== null && !declared.has(service)) findings.push(found(HFS_BACKING_UNDECLARED, rel, `${rel} ${section} has ${name}, a client of ${service}, which hfs.json sides.be.backing does not declare: declare ${service} for the capability that needs it, or remove the dependency`, { section, name, service }));
     }

package/runtime/scripts/hfs/rules/env-parity.mjs

@@ -32,7 +32,7 @@ export const ENV_EXAMPLE_DRIFT = 'ENV_EXAMPLE_DRIFT';
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const ENV_SOURCE = /(?:\.env|\.config)\.ts$/u;
 const APP_MAIN = /(?:^|\/)apps\/[^/]+\/src\/main\.ts$/u;
-const SEALED_MEMBER = /^\.starcistacks\/[^/]+\/secrets\/[^/]+\.enc$/u;
+const SEALED_MEMBER = /^\.starcistacks\/[^/]+\/secrets\/[^/]+\.enc(?:\.yaml)?$/u;
 const KEYS_ROSTER = /^\.starcistacks\/[^/]+\/runtime\/env\/KEYS\.md$/u;
 const STACK_YAML = /^\.starcistacks\/.+\.ya?ml$/u;
 const KEY_NAME = /^[A-Za-z_]\w*$/u;

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

@@ -11,7 +11,7 @@ const LOCKFILE = /(^|\/)package-lock\.json$/u;
 const ROOT_ENV = /^\.env(?:\..*)?$/iu;
 const SECRETS_ENV = /^secrets\.env$/iu;
 const SECRETS_DIRECTORY = /^\.secrets(?:\/|$)/iu;
-const SEALED_HOME = /^\.starcistacks\/[^/]+\/secrets\/[^/]+\.enc$/iu;
+const SEALED_HOME = /^\.starcistacks\/[^/]+\/secrets\/[^/]+\.enc(?:\.yaml)?$/iu;
 
 const LITE_SECRET_PATTERNS = Object.freeze([
   { name: 'supabase-personal-access-token', re: /\bsbp_[A-Za-z0-9_-]{20,}\b/u },
@@ -52,10 +52,10 @@ function custodyPathFinding(file, repo, findings) {
       findings.push(found(LITE_SECRET_CUSTODY, file, `${file} is forbidden at the lite app root; lite keeps no .env*, secrets.env or .secrets/ custody path.`, { pattern: 'lite-forbidden-entry' }));
       return true;
     }
-    if (file.endsWith('.enc') && !SEALED_HOME.test(file)) {
+    if (/\.enc(?:\.yaml)?$/iu.test(file) && !SEALED_HOME.test(file)) {
       findings.push(found(LITE_SECRET_CUSTODY, file, `${file} is a sealed file outside .starcistacks/<env>/secrets/; lite has exactly one encrypted custody path.`, { pattern: 'sealed-file-home' }));
     }
-  } else if (file.endsWith('.enc')) {
+  } else if (/\.enc(?:\.yaml)?$/iu.test(file)) {
     findings.push(found(LITE_SECRET_CUSTODY, file, `${file} is a sealed file inside a side tree; lite keeps *.enc only at the app root under .starcistacks/<env>/secrets/.`, { pattern: 'sealed-file-home' }));
   }
   return false;

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

@@ -7,7 +7,7 @@ const PLAINTEXT_LOAD = 'HFS_SCRIPT_PLAINTEXT_LOAD';
 const XTRACE = 'HFS_SCRIPT_XTRACE';
 const SECRET_ENV_FILE = /(?:^|\/)(?:secrets?\.env|\.env)(?:\.[^/]*)?/iu;
 const SECRET_NIVO_FILE = /(?:^|\/)\.nivo-lite(?:\/|$)/iu;
-const SECRET_ENC_FILE = /\.enc$/iu;
+const SECRET_ENC_FILE = /\.enc(?:\.yaml)?$/iu;
 const isSecretFile = (file) => SECRET_ENV_FILE.test(file) || SECRET_NIVO_FILE.test(file) || SECRET_ENC_FILE.test(file);
 const EXCLUDED_TREE = /(?:^|\/)(?:node_modules|\.git|\.claude|\.secrets|secrets|tests?|__tests__|docs|coverage|dist|build)(?:\/|$)/u;
 const TEST_FILE = /(?:\.(?:spec|test)|-spec)\.[cm]?[jt]sx?$/u;

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

@@ -21,7 +21,7 @@ const ENV_FILE = /(?:^|\/)[^/.][^/]*\.env(?:\.(?!example|sample|template)[^/]*)?
 // which R06 already judges, and the sealed `.enc` members, which are custody.
 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$/;
+const SEALED_HOME = /^\.starcistacks\/[^/]+\/secrets\/[^/]+\.enc(?:\.yaml)?$/;
 
 const KEY_LINE = /^\s*(?:export\s+)?([A-Za-z_$][\w$]*)\s*=/;
 const hasSecretKeys = (file, text) =>
@@ -40,7 +40,7 @@ export function secretCustodyOnlyFindings({ repoRoot, files, repo, inScope }) {
   const findings = [];
   for (const file of files.filter((f) => !inScope || inScope(f))) {
     const posix = file.replaceAll('\\', '/');
-    if (file.endsWith('.enc')) {
+    if (/\.enc(?:\.yaml)?$/.test(file)) {
       findings.push(...sealedCustodyFindings(file, posix, repo));
       continue;
     }

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

@@ -38,7 +38,7 @@ 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 (file.endsWith('.enc')) 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' })];
+  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 })) {

package/runtime/scripts/hfs/rules/stack-tooling.mjs

@@ -15,7 +15,7 @@ const SOURCE_FILE = /(?:^|\/)[^/.]+$|\.(?:sh|bash|zsh|mjs|cjs|js|ts|mts|py|ya?ml
 const TEST_FILE = /\.(?:spec|test)\.[cm]?[jt]s$/;
 const CREDENTIAL_ENV_FILE = /(?:^|\/)(?:secrets?\.env|\.env)(?:\.[^/]*)?/i;
 const CREDENTIAL_SECRETS_DIR = /(?:^|\/)secrets\//i;
-const CREDENTIAL_ENC_FILE = /\.enc$/i;
+const CREDENTIAL_ENC_FILE = /\.enc(?:\.yaml)?$/i;
 const isCredentialFile = (file) => CREDENTIAL_ENV_FILE.test(file) || CREDENTIAL_SECRETS_DIR.test(file) || CREDENTIAL_ENC_FILE.test(file);
 const VERB_FILE = /^(render|provision|converge|verify|prune|rollback|release|backup|prepare|doctor|jobs|public)\.(?:mjs|js|cjs|sh)$/;
 const COMMENT_LINE = /^[ \t]*(?:#|\/\/).*$/gm;

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

@@ -3,6 +3,7 @@
 // probe of the real tree: the files below .starcistacks/<env>/, the services of the first composeFiles entry and the sealed members.
 // One finding per problem; an environment without a deploy block is not a finding.
 import fs from 'node:fs';
+import { isSealedName, memberOfName } from '../../lib/sealed-member.mjs';
 import path from 'node:path';
 import { isPlainObject as plain } from '../../../engine/plain-object.mjs';
 import { findStackDeclaration, readDeclaration, STACK_ROOT } from '../../lib/stack-declaration.mjs';
@@ -23,7 +24,7 @@ function stackServices(envDir, spec) {
 
 function sealedMembers(envDir) {
   try {
-    return new Set(fs.readdirSync(path.join(envDir, 'secrets')).filter((name) => name.endsWith('.enc')).map((name) => name.slice(0, -4)));
+    return new Set(fs.readdirSync(path.join(envDir, 'secrets')).filter(isSealedName).map(memberOfName));
   } catch { return new Set(); }
 }
 

package/runtime/scripts/hfs/rules/stacks-lite-backing.mjs

@@ -1,4 +1,4 @@
-// R276: lite runs exactly its own PostgreSQL (the db component, the image its managed db/Dockerfile builds) with pgvector, admits only the backing services available to its edition,
+// R276: lite runs exactly its own PostgreSQL (the db component, the image its managed .starcistacks/images/db/Dockerfile builds) with pgvector, admits only the backing services available to its edition,
 // and runs a declared Redis as one service with AOF fsynced at least every second on a named volume and no eviction
 // (ruling:R212/case-10, owner:lite-vector-is-pgvector); sidecar SQLite persists on declared named volumes.
 import { isPlainObject as plain } from '../../../engine/plain-object.mjs';
@@ -45,7 +45,7 @@ function imageIssues(components, services, { catalog, declared }) {
       const service = serviceOfImage(catalog, entry.image);
       if (DATABASE_IMAGE.test(repositoryOf(entry.image)))
         errors.push({ code: 'STACKS_LITE_SELFHOSTED_DB', at: `${prefix}.${id}.image`,
-          message: 'lite runs one database, the db component of the image db/Dockerfile builds (the official postgres image plus pgvector); no other Postgres or Mongo image' });
+          message: 'lite runs one database, the db component of the image .starcistacks/images/db/Dockerfile builds (the official postgres image plus pgvector); no other Postgres or Mongo image' });
       else if (service !== null && !judgedInEdition(catalog[service], 'lite'))
         errors.push({ code: 'STACKS_LITE_SELFHOSTED_DB', at: `${prefix}.${id}.image`,
           message: `lite must not run ${service}; vector search uses pgvector in the db service (owner:lite-vector-is-pgvector)` });

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

@@ -18,7 +18,7 @@ const issueFinding = (file, issue) => found(CODE, file, `${file}: ${issue.at}: $
 /** The app's tracked automation sources; locations are reported without returning any source text. */
 export function hostCrontabFindings({ repoRoot, files }) {
   const findings = [];
-  for (const file of files.filter(file => HOST_CRON_PATH.test(file) && !file.endsWith('.enc'))) {
+  for (const file of files.filter(file => HOST_CRON_PATH.test(file) && !/\.enc(?:\.yaml)?$/.test(file))) {
     const text = readText(repoRoot, file);
     if (text === null) continue;
     for (const [index, line] of text.split(/\r?\n/).entries()) {
@@ -81,7 +81,7 @@ function loadSwarmModel({ repoRoot, environment, spec, files, findings }) {
 function swarmDeploymentFiles(repoRoot, files) {
   return files.filter(file => {
     const environment = /^\.starcistacks\/([^/]+)\/infra\/swarm\//.exec(file)?.[1];
-    if (!environment || file.endsWith('.enc')) return false;
+    if (!environment || /\.enc(?:\.yaml)?$/.test(file)) return false;
     const target = safeStackFile(repoRoot, path.resolve(repoRoot, '.starcistacks', environment), file.split('/').slice(2).join('/'));
     if (!target) return true;
     const parsed = readDeclaration(target);

package/runtime/scripts/hfs/rules/stacks-swarm.mjs

@@ -161,7 +161,7 @@ function safeRegularFile(repoRoot, file) {
 }
 
 function trackedConfigText(input, relative) {
-  if (!present(relative) || relative.endsWith('.enc') || path.isAbsolute(relative)) return null;
+  if (!present(relative) || /\.enc(?:\.yaml)?$/.test(relative) || path.isAbsolute(relative)) return null;
   const directory = `.starcistacks/${input.environment}/`;
   const stack = input.spec.renderedModel ?? input.spec.composeFiles?.[0] ?? 'infra/swarm/stack.yaml';
   const file = path.posix.normalize(path.posix.join(directory, path.posix.dirname(stack), relative));

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

@@ -15,7 +15,7 @@ import { hostCrontabFindings, stacksRuntimeFindings } from './stacks-runtime.mjs
 const STACKS_SHAPE = 'HFS_STACKS_SHAPE';
 const STACKS_SLOT = 'app.starcistacks';
 const HOST_SONAR_ROOT = '.claude/ext/sonar';
-const INSIDE_SECRETS = /^[^/]+\/secrets\/[^/]+\.enc$/;
+const INSIDE_SECRETS = /^[^/]+\/secrets\/[^/]+\.enc(?:\.yaml)?$/;
 
 /** The anchored expressions of a slot's `allows` entries: `<name>` is one path segment, braces alternate. */
 const allowedExpressions = (allows) => allows.flatMap((entry) => braceVariants(entry.replace(/<[a-z][a-z0-9-]*>/g, '*'))).map((variant) => globExpression(variant.endsWith('/') ? `${variant}**` : variant));
@@ -26,8 +26,8 @@ function treeFindings(files, allowed, prefix) {
   const findings = [];
   for (const file of files.filter((f) => f.startsWith(prefix))) {
     const rel = file.slice(prefix.length);
-    if (rel.endsWith('.enc') && !INSIDE_SECRETS.test(rel)) findings.push(shapeFinding(file, `${file} is a sealed secret outside <env>/secrets/<slug>.enc; move it to .starcistacks/<env>/secrets/`));
-    else if (!allowed.some((expression) => expression.test(rel))) findings.push(shapeFinding(file, `${file} is not part of the standard .starcistacks shape (application-stacks.yaml and <env>/{README.md, environment.json, infra, runtime/{config,env}, secrets/<slug>.enc, seeds}); move or delete it`));
+    if (/\.enc(?:\.yaml)?$/.test(rel) && !INSIDE_SECRETS.test(rel)) findings.push(shapeFinding(file, `${file} is a sealed secret outside <env>/secrets/<slug>.enc; move it to .starcistacks/<env>/secrets/`));
+    else if (!allowed.some((expression) => expression.test(rel))) findings.push(shapeFinding(file, `${file} is not part of the standard .starcistacks shape (application-stacks.yaml, images/db/Dockerfile in lite and <env>/{README.md, environment.json, infra, runtime/{config,env}, secrets/<slug>.enc, seeds}); move or delete it`));
   }
   return findings;
 }

package/runtime/scripts/hfs/sealed-members.mjs

@@ -5,10 +5,11 @@ import { randomUUID } from 'node:crypto';
 import { parseYaml } from '../../engine/yaml.mjs';
 import { byCodeUnit } from '../lib/list.mjs';
 import { setSecretValues } from './secret-store.mjs';
+import { memberFile } from '../lib/sealed-member.mjs';
 import { sealBootstrapValues } from './secret-bootstrap-crypto.mjs';
 
 const ENVIRONMENT = /^[a-z0-9][a-z0-9-]*$/u;
-const MEMBER = /^secrets\/([a-z0-9][a-z0-9-]*)(?:\.enc)?$/u;
+const MEMBER = /^secrets\/([a-z0-9][a-z0-9-]*)(?:\.enc(?:\.yaml)?)?$/u;
 const KEY = /^[A-Z][A-Z0-9_]*$/u;
 
 function readDocument(file, format) {
@@ -33,7 +34,7 @@ function rosterKeys(repoRoot, member) {
   for (const line of fs.readFileSync(file, 'utf8').split(/\r?\n/u)) {
     const key = /^\|\s*`([A-Z][A-Z0-9_]*)`\s*\|/u.exec(line)?.[1];
     if (!key) continue;
-    const locations = [...line.matchAll(/(?:secrets\/|\/run\/secrets\/)([a-z0-9][a-z0-9-]*)(?:\.enc)?/gu)];
+    const locations = [...line.matchAll(/(?:secrets\/|\/run\/secrets\/)([a-z0-9][a-z0-9-]*)(?:\.enc(?:\.yaml)?)?/gu)];
     if (locations.some((match) => match[1] === member.slug)) keys.push(key);
   }
   return keys;
@@ -84,16 +85,19 @@ function placeholderValue(key) {
 export function materializeDeclaredPlaceholders(repoRoot, { recipient, recipientsForFile, processEnv = process.env, sops, write, only = () => true } = {}) {
   const members = [];
   for (const member of declaredSealedMembers(repoRoot).filter((declared) => only(declared))) {
-    const relative = `.starcistacks/${member.env}/secrets/${member.slug}.enc`;
-    if (fs.existsSync(path.join(repoRoot, relative))) continue;
-    const age = recipientsForFile?.(path.join(repoRoot, relative)) ?? [recipient];
+    const directory = path.join(repoRoot, '.starcistacks', member.env, 'secrets');
+    if (fs.existsSync(memberFile(directory, member.slug))) continue;
+    // The sops-free bootstrap sealer writes dotenv only, so its placeholder is a legacy `.enc` until `migrate` moves it.
+    const file = sops ? memberFile(directory, member.slug) : path.join(directory, `${member.slug}.enc`);
+    const relative = path.relative(repoRoot, file).split(path.sep).join('/');
+    const age = recipientsForFile?.(file) ?? [recipient];
     if (!age.length || age.some((value) => !/^age1[a-z0-9]+$/u.test(value ?? '')))
       throw new Error('sealed placeholders require the app public age recipient');
     if (!sops && age.length !== 1) throw new Error('multiple recipients require the standard SOPS adapter');
     const values = Object.fromEntries(member.keys.map((key) => [key, placeholderValue(key)]));
     const adapter = sops ?? { seal: () => sealBootstrapValues({ values, recipient: age[0] }) };
     setSecretValues(repoRoot, { slug: member.slug, values, env: member.env }, {
-      age, processEnv, sops: adapter, write,
+      age, processEnv, sops: adapter, write, legacy: !sops,
     });
     members.push(relative);
   }

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

@@ -122,3 +122,19 @@ export function writeSecretFile(directory, key, value) {
   }
   return file;
 }
+
+/**
+ * The main checkout of a git worktree (its `.git` file names `<main>/.git/worktrees/<name>`), else `root` itself: a worktree
+ * keeps no git-ignored `.claude/secret.env` of its own, so the app's age identity is read from the checkout it was cut from.
+ */
+export function mainCheckout(root) {
+  const dotGit = path.join(root, ".git");
+  const stat = fs.lstatSync(dotGit, { throwIfNoEntry: false });
+  if (!stat?.isFile()) return root;
+  const gitdir = /^gitdir:\s*(.+)$/mu
+    .exec(fs.readFileSync(dotGit, "utf8"))?.[1]
+    ?.trim()
+    .replaceAll("\\", "/");
+  const main = gitdir && /^(.*)\/\.git\/worktrees\/[^/]+$/u.exec(gitdir)?.[1];
+  return main && fs.existsSync(main) ? path.resolve(main) : root;
+}

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

@@ -12,12 +12,18 @@ import { generateAppIdentity } from "./secret-bootstrap-crypto.mjs";
 import { materializeDeclaredPlaceholders } from "./sealed-members.mjs";
 import { defaultSops } from "./secret-sops.mjs";
 import {
+  mainCheckout,
   outsideRepository,
   privateDirectory,
   secretRoots,
 } from "./secret-files.mjs";
 
-const PATH_RULE = String.raw`\.starcistacks[/\\][^/\\]+[/\\]secrets[/\\][^/\\]+\.enc$`;
+const PATH_RULE = String.raw`\.starcistacks[/\\][^/\\]+[/\\]secrets[/\\][^/\\]+\.enc(?:\.yaml)?$`;
+/** The rule an earlier init wrote, which matches legacy `.enc` members only; init and recipients treat it as the app's own. */
+const LEGACY_PATH_RULE = String.raw`\.starcistacks[/\\][^/\\]+[/\\]secrets[/\\][^/\\]+\.enc$`;
+/** The path_regex of one environment's rule: its members, current or legacy. */
+export const environmentRule = (environment) =>
+  String.raw`\.starcistacks[/\\]` + environment + String.raw`[/\\]secrets[/\\][^/\\]+\.enc(?:\.yaml)?$`;
 const AGE_IDENTITY_NAME = /^SOPS_AGE_KEY(?:_FILE)?$/i;
 
 /** Bootstrap a new app with its own age identity; only its public recipient leaves this owner. */
@@ -63,22 +69,46 @@ export function initializeAppIdentity(repoRoot, { write, tools } = {}) {
   }
 }
 
-/** Load host-local age selections below the explicit environment, without copying any other credentials. */
-export function ageIdentityEnv(repoRoot, env, tools) {
+/**
+ * The app's host-local age selection: SOPS_AGE_KEY or SOPS_AGE_KEY_FILE of the explicit environment, else of the git-ignored
+ * `.claude/secret.env` of the app root, else of its main checkout's when the root is a git worktree, else the SOPS_AGE_KEY the
+ * `host` port reads (the harness CLI's secret.env: `{ label, read }`, read only when nothing before it selects one). `env` is the explicit
+ * environment with that selection added below it (no other credential is copied); `source` names where it came from, or is
+ * null; `looked` lists every secret.env read, for a refusal that names them. No value ever leaves in `source` or `looked`.
+ */
+export function localAgeIdentity(repoRoot, env, tools, host = null) {
+  const own = Object.keys(env).filter((name) => AGE_IDENTITY_NAME.test(name));
+  if (own.length) return { env: { ...env }, source: `the environment (${own.join(", ")})`, looked: [] };
   const load = tools?.secretEnv ?? secretEnv;
-  let resolved = {};
-  try {
-    resolved = load(path.join(repoRoot, ".claude"), env) ?? {};
-  } catch {
-    return { ...env };
+  const roots = [...new Set([repoRoot, mainCheckout(repoRoot)].map((root) => path.resolve(root)))];
+  const looked = [];
+  for (const root of roots) {
+    const file = path.join(root, ".claude", "secret.env");
+    looked.push(file);
+    let resolved;
+    try {
+      resolved = load(path.join(root, ".claude"), env) ?? {};
+    } catch {
+      continue;
+    }
+    const local = Object.fromEntries(
+      Object.entries(resolved).filter(([name]) => AGE_IDENTITY_NAME.test(name)),
+    );
+    if (Object.keys(local).length)
+      return { env: { ...env, ...local }, source: `${file} (${Object.keys(local).join(", ")})`, looked };
   }
-  const own = new Set(Object.keys(env).map((name) => name.toUpperCase()));
-  const local = Object.fromEntries(
-    Object.entries(resolved).filter(
-      ([name]) => AGE_IDENTITY_NAME.test(name) && !own.has(name.toUpperCase()),
-    ),
-  );
-  return { ...env, ...local };
+  if (host) {
+    looked.push(host.label);
+    const value = host.read();
+    if (typeof value === "string" && value.trim())
+      return { env: { ...env, SOPS_AGE_KEY: value.trim() }, source: `${host.label} (SOPS_AGE_KEY)`, looked };
+  }
+  return { env: { ...env }, source: null, looked };
+}
+
+/** Load host-local age selections below the explicit environment (localAgeIdentity), without copying any other credentials. */
+export function ageIdentityEnv(repoRoot, env, tools) {
+  return localAgeIdentity(repoRoot, env, tools).env;
 }
 
 /** Select the first matching public age rule, including for SOPS's isolated CI identity path. */
@@ -98,12 +128,16 @@ export function configuredRecipients(repoRoot, file) {
     throw new Error(
       ".sops.yaml requires creation_rules; run starci app secret init",
     );
+  // A `.enc.yaml` member also matches a rule written for the legacy `.enc` spelling, so an app's existing .sops.yaml keeps
+  // sealing until `starci app secret recipients` rewrites it.
+  const spellings = [relative, ...(relative.endsWith(".enc.yaml") ? [relative.slice(0, -".yaml".length)] : [])];
   const rule = config.creation_rules.find((entry) => {
     try {
       return (
         !entry.path_regex ||
-        new RegExp(entry.path_regex).test(relative) ||
-        new RegExp(entry.path_regex).test(relative.replaceAll("/", "\\"))
+        spellings.some((spelling) =>
+          new RegExp(entry.path_regex).test(spelling) ||
+          new RegExp(entry.path_regex).test(spelling.replaceAll("/", "\\")))
       );
     } catch {
       throw new Error(".sops.yaml has an invalid path_regex");
@@ -163,7 +197,7 @@ function readInitializationConfig(configFile) {
 function existingInitializationRule(rules) {
   const canonical = rules.find(
     (rule) =>
-      rule?.path_regex === PATH_RULE &&
+      [PATH_RULE, LEGACY_PATH_RULE].includes(rule?.path_regex) &&
       typeof rule.age === "string" &&
       rule.age.trim(),
   );
@@ -250,8 +284,73 @@ function initializationRecipient(repoRoot, env, platform, tool, tools) {
   return result.publicRecipient;
 }
 
+/**
+ * The public recipient of the owner's age identity, as localAgeIdentity finds it (`host` its last source). Only an inline
+ * SOPS_AGE_KEY is derived; with none the caller names the recipient itself.
+ */
+export function ownerRecipient(repoRoot, env, { platform, tools, host = null }) {
+  const local = localAgeIdentity(repoRoot, env, tools, host);
+  if (!Object.keys(local.env).some((name) => /^SOPS_AGE_KEY$/i.test(name)))
+    throw new Error(
+      `no SOPS_AGE_KEY found (looked in the environment${local.looked.length ? `, ${local.looked.join(", ")}` : ""}); name the owner's public recipient (age1...) instead of owner`,
+    );
+  return initializationRecipient(repoRoot, local.env, platform, secretTools(env, tools), tools);
+}
+
+/**
+ * `starci app secret recipients <env> [--add <age1...|owner>] [--remove <age1...|owner>]`: prints the public recipients a
+ * member of the environment is sealed to, or rewrites the environment's own rule of the app's managed .sops.yaml (one rule per
+ * environment, written before the app-wide rule, public keys only). `owner` is the owner identity's recipient (ownerRecipient).
+ * A member sealed before keeps its recipients until it is sealed again.
+ */
+export function environmentRecipients(repoRoot, environment, { add = [], remove = [], owner, stdout }) {
+  const configFile = path.join(repoRoot, ".sops.yaml");
+  const config = readInitializationConfig(configFile);
+  const rules = Array.isArray(config.creation_rules) ? config.creation_rules : [];
+  const probe = path.join(repoRoot, ".starcistacks", environment, "secrets", "member.enc.yaml");
+  let current = [];
+  try { current = configuredRecipients(repoRoot, probe); } catch { current = []; }
+  if (!add.length && !remove.length) {
+    stdout(`${environment}: ${current.join(", ") || "no rule names a recipient; run starci app secret init"}\n`);
+    return 0;
+  }
+  let ownerValue;
+  const resolve = (value) => {
+    if (value !== "owner") return value;
+    ownerValue ??= owner();
+    return ownerValue;
+  };
+  const next = [...current];
+  for (const value of add.map(resolve)) {
+    if (!/^age1[a-z0-9]+$/u.test(value)) throw new Error(`${value} is not a public age recipient (age1...)`);
+    if (!next.includes(value)) next.push(value);
+  }
+  for (const value of remove.map(resolve)) {
+    const at = next.indexOf(value);
+    if (at < 0) throw new Error(`${environment} is not sealed to ${value}`);
+    next.splice(at, 1);
+  }
+  if (!next.length) throw new Error(`${environment} keeps at least one recipient`);
+  const regex = environmentRule(environment);
+  const own = rules.findIndex((rule) => rule?.path_regex === regex);
+  if (own >= 0) rules[own] = { ...rules[own], age: next.join(",") };
+  else {
+    const appWide = rules.findIndex((rule) => !rule?.path_regex || [PATH_RULE, LEGACY_PATH_RULE].includes(rule.path_regex));
+    rules.splice(appWide < 0 ? rules.length : appWide, 0, { path_regex: regex, age: next.join(",") });
+  }
+  config.creation_rules = rules;
+  fs.writeFileSync(
+    configFile,
+    `# Managed by starci app secret init and recipients: one rule per environment, public age recipients only.\n${stringifyYaml(config)}`,
+  );
+  stdout(
+    `${environment}: ${next.join(", ")}; a member sealed before keeps its recipients until it is sealed again (starci app secret migrate ${environment} <member> --execute)\n`,
+  );
+  return 0;
+}
+
 /** Reuse an existing matching age rule; initialization must not rotate an app's recipient. */
-export function initializeSecrets(repoRoot, { env, platform, tools, stdout }) {
+export function initializeSecrets(repoRoot, { env, platform, tools, stdout, host = null }) {
   const configFile = path.join(repoRoot, ".sops.yaml");
   const config = readInitializationConfig(configFile);
   const rules = config.creation_rules ?? [];
@@ -264,7 +363,7 @@ export function initializeSecrets(repoRoot, { env, platform, tools, stdout }) {
     throw new Error(
       ".sops.yaml must name valid public age recipients; initialization never prints private key material",
     );
-  const localEnv = ageIdentityEnv(repoRoot, {}, tools);
+  const localEnv = localAgeIdentity(repoRoot, {}, tools, host).env;
   const selectedEnv = ageIdentityEnv(repoRoot, existing ? env : { ...env, ...localEnv }, tools);
   if (!existing && !Object.keys(localEnv).some((name) => /^SOPS_AGE_KEY$/i.test(name))) {
     const initialized = initializeAppIdentity(repoRoot, { tools });
@@ -276,7 +375,7 @@ export function initializeSecrets(repoRoot, { env, platform, tools, stdout }) {
   const inline = Object.keys(selectedEnv).some((name) => /^SOPS_AGE_KEY$/i.test(name));
   const derived = existing && !inline ? existing.age : initializationRecipient(repoRoot, selectedEnv, platform, tool, tools);
   const recipient = existing?.age ?? derived;
-  const exact = rules.findIndex((rule) => rule?.path_regex === PATH_RULE);
+  const exact = rules.findIndex((rule) => [PATH_RULE, LEGACY_PATH_RULE].includes(rule?.path_regex));
   if (exact >= 0) rules[exact] = { ...rules[exact], age: recipient };
   // SOPS uses the first matching rule: keep any existing environment-specific recipients in force.
   else rules.push({ path_regex: PATH_RULE, age: recipient });

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

@@ -5,6 +5,7 @@ import { byCodeUnit } from "../lib/list.mjs";
 import { materializedDirectory, writeSecretFile } from "./secret-files.mjs";
 import { envelopeOf, validateKey } from "./secret-document.mjs";
 import { fileOf, readMap, sealedFiles } from "./secret-store.mjs";
+import { memberOfName } from "../lib/sealed-member.mjs";
 import { SecretError, publicStorage } from "./secret-errors.mjs";
 
 function validateWindowsKeys(map) {
@@ -72,7 +73,7 @@ export function materializeSecrets(directory, sops, output) {
   const map = Object.create(null);
   for (const name of sealedFiles(directory)) {
     for (const [item, value] of Object.entries(
-      readMap(fileOf(directory, name.slice(0, -4)), sops),
+      readMap(fileOf(directory, memberOfName(name)), sops),
     )) {
       if (Object.hasOwn(map, item))
         throw new SecretError(