@starci/hfs 5.1.0 → 5.2.0

package/runtime/scripts/hfs/architecture/identity.mjs

@@ -1,57 +1,17 @@
-// identity.mjs - the back-end identity machine. Under lite the one token verifier is be.integrations.passport: jose's jwtVerify
-// there checks the app's OWN key set (createLocalJWKSet over the keys it signs with, never createRemoteJWKSet), pins issuer,
-// audience and algorithms, and no file decodes a token unverified or reads authorization claims from a request body (R329).
-// In both editions every jwtVerify call holds the JWT policy (R260, jwtPolicyProblems).
+// identity.mjs - the back-end identity machine. Under lite the one token verifier is @starci/auth, composed by be.integrations.passport:
+// no app file calls jose's jwtVerify, decodes a token unverified or reads authorization claims from a request body (R329), and the
+// passport integration imports @starci/auth/server. In both editions every jwtVerify call holds the JWT policy (R260, jwtPolicyProblems).
 import path from 'node:path';
 import { machineKit } from './machine-ast.mjs';
-import { fromConfig, importedFrom, jwtPolicyProblems, reportAt, unwrap } from './jwt-ast.mjs';
+import { jwtPolicyProblems, reportAt, unwrap } from './jwt-ast.mjs';
 import { accessName } from '../../lib/ts-ast.mjs';
 const PASSPORT_SLOT = 'be.integrations.passport';
+const PACKAGE_ENTRY = '@starci/auth/server';
 const BE_JWT_VERIFIED = 'BE_AUTH_JWT_OWN_JWKS';
 /** The rule ids the back-end identity machine reports. */
 export const IDENTITY_RULE_IDS = Object.freeze(['BE_AUTH_JWT_OWN_JWKS', 'BE_JWT_ALG_PINNED']);
 const JWT_MODULES = new Set(['jose', 'jsonwebtoken', 'jwt-decode']);
 const CLAIM_NAMES = new Set(['role', 'roles', 'membership', 'memberships']);
-const objectLiteral = (kit, checker, node) => {
-    const current = unwrap(kit.ts, node);
-    if (!current)
-        return null;
-    if (kit.ts.isObjectLiteralExpression(current))
-        return current;
-    if (!kit.ts.isIdentifier(current))
-        return null;
-    for (const declaration of kit.declarationsOf(checker, current)) {
-        if (kit.ts.isVariableDeclaration(declaration) && declaration.initializer) {
-            const value = unwrap(kit.ts, declaration.initializer);
-            if (kit.ts.isObjectLiteralExpression(value))
-                return value;
-        }
-    }
-    return null;
-};
-const staticStrings = (kit, checker, node) => {
-    const current = unwrap(kit.ts, node);
-    if (kit.ts.isStringLiteralLike(current))
-        return [current.text];
-    if (kit.ts.isArrayLiteralExpression(current)) {
-        const literals = current.elements.filter((element) => kit.ts.isStringLiteralLike(element));
-        if (literals.length === current.elements.length)
-            return literals.map((element) => element.text);
-    }
-    const value = kit.stringValue(checker, current);
-    return value === null ? null : [value];
-};
-const jwksArgument = (kit, checker, node) => {
-    const current = unwrap(kit.ts, node);
-    if (!current)
-        return false;
-    if (kit.ts.isCallExpression(current))
-        return importedFrom(kit, checker, current.expression, new Set(['jose']), new Set(['createLocalJWKSet']));
-    if (!kit.ts.isIdentifier(current))
-        return false;
-    return kit.declarationsOf(checker, current).some((declaration) => kit.ts.isVariableDeclaration(declaration) && declaration.initializer
-        && jwksArgument(kit, checker, declaration.initializer));
-};
 const importedCall = (kit, checker, call) => {
     const direct = kit.importBinding(checker, call.expression);
     if (direct?.module === 'jwt-decode' && direct.name === 'default')
@@ -84,41 +44,16 @@ const fromRequestBody = (kit, checker, node, seen = new Set()) => {
     return kit.declarationsOf(checker, current).some(declaration => kit.ts.isVariableDeclaration(declaration) && declaration.initializer
         && fromRequestBody(kit, checker, declaration.initializer, seen));
 };
-function verifyJwtCall(kit, checker, file, node, counters, violations) {
-    counters.verifyCalls += 1;
-    if (file.slot !== PASSPORT_SLOT) {
-        reportAt(violations, kit, BE_JWT_VERIFIED, file, node, `jwtVerify is called outside ${PASSPORT_SLOT}; the integration is the one token verifier.`);
-        return true;
-    }
-    const options = objectLiteral(kit, checker, node.arguments[2]);
-    const property = (name) => options ? kit.propertyOf(options, name) : null;
-    const values = (name) => {
-        const entry = property(name);
-        return entry ? staticStrings(kit, checker, kit.valueOfProperty(entry)) : null;
-    };
-    const issuer = property('issuer');
-    const audience = values('audience');
-    const algorithms = values('algorithms');
-    // The audience is pinned by a literal or, as R260 accepts, by typed configuration (the skeleton's TokenOptions.audience).
-    const audienceEntry = property('audience');
-    const pinnedAudience = (audience !== null && audience.length > 0)
-        || (audienceEntry != null && fromConfig(kit.ts, checker, kit.valueOfProperty(audienceEntry)));
-    const good = jwksArgument(kit, checker, node.arguments[1]) && issuer != null && pinnedAudience
-        && algorithms !== null && algorithms.length > 0;
-    if (!good) {
-        reportAt(violations, kit, BE_JWT_VERIFIED, file, node, 'jwtVerify must check the app\'s own key set (createLocalJWKSet(...) over the keys integrations/passport signs with) and pin issuer, audience and a non-empty algorithms list; jwtVerify then enforces signature and exp.');
-    }
-    else
-        counters.verifiedCalls += 1;
-    return false;
-}
 function inspectJwtCall(kit, checker, file, node, counters, violations) {
     const binding = importedCall(kit, checker, node);
     if (binding && JWT_MODULES.has(binding.module) && ['decode', 'decodeJwt', 'jwtDecode'].includes(binding.name)) {
         reportAt(violations, kit, BE_JWT_VERIFIED, file, node, `${binding.module}.${binding.name} decodes a token without proving its signature; verify it through integrations/passport.`, { module: binding.module, method: binding.name });
     }
-    if (binding?.module === 'jose' && binding.name === 'jwtVerify')
-        return verifyJwtCall(kit, checker, file, node, counters, violations);
+    if (binding?.module === 'jose' && binding.name === 'jwtVerify') {
+        counters.verifyCalls += 1;
+        reportAt(violations, kit, BE_JWT_VERIFIED, file, node, 'jwtVerify is called in the app; @starci/auth verifies the own access tokens, reached through ' + PASSPORT_SLOT + '.');
+        return true;
+    }
     return false;
 }
 function inspectRequestClaims(kit, file, node, checker, violations) {
@@ -146,18 +81,18 @@ function checkOwnJwks(input) {
     const violations = [];
     const integrations = [...input.graph.files.values()].filter((file) => file.slot === PASSPORT_SLOT);
     if (!integrations.length)
-        return { violations, coverage: { status: 'not-applicable', integrationFiles: 0, verifiedCalls: 0 } };
-    const counters = { verifyCalls: 0, verifiedCalls: 0 };
+        return { violations, coverage: { status: 'not-applicable', integrationFiles: 0, verifyCalls: 0 } };
+    const counters = { verifyCalls: 0 };
     for (const file of input.graph.files.values()) {
         const checker = kit.checkerOf(file.sourceFile);
         kit.walk(file.sourceFile, (node) => inspectBackendNode(kit, checker, file, node, counters, violations));
     }
-    if (counters.verifyCalls === 0) {
-        const anchor = integrations.find((file) => path.posix.basename(file.rel).endsWith('.tokens.ts')) ?? integrations[0];
-        if (anchor)
-            reportAt(violations, kit, BE_JWT_VERIFIED, anchor, anchor.sourceFile, `${PASSPORT_SLOT} has no jose.jwtVerify call backed by createLocalJWKSet over the app's own keys.`);
-    }
-    return { violations, coverage: { status: 'checked', integrationFiles: integrations.length, verifyCalls: counters.verifyCalls, verifiedCalls: counters.verifiedCalls } };
+    const composes = integrations.some((file) => file.sourceFile.statements.some((statement) => kit.ts.isImportDeclaration(statement)
+        && kit.ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === PACKAGE_ENTRY));
+    const anchor = integrations.find((file) => path.posix.basename(file.rel) === 'index.ts') ?? integrations[0];
+    if (!composes && anchor)
+        reportAt(violations, kit, BE_JWT_VERIFIED, anchor, anchor.sourceFile, PASSPORT_SLOT + ' does not import ' + PACKAGE_ENTRY + ', the one verifier of the own access tokens.');
+    return { violations, coverage: { status: 'checked', integrationFiles: integrations.length, verifyCalls: counters.verifyCalls, composesPackage: composes } };
 }
 /** R260 BE_JWT_ALG_PINNED: every jose jwtVerify call pins a literal secure algorithm list and a configured issuer, and binds the principal by a configured audience or the authenticated role. */
 export function checkJwtPolicy(input) {

package/runtime/scripts/hfs/architecture/transport-owner.d.mts

@@ -15,8 +15,7 @@ import type { ArchitectureViolation, CheckInput } from './hfs-graph.mjs';
  *   - no file outside the client folder and the stream reader folder (`fe.transport.stream`, `modules/api/sse/clients/`) references the global `fetch`: a call, `globalThis.fetch`, `window.fetch`, or a
  *     reference passed as a value (`useSWR(key, fetch)`, `const send = fetch`), all of which a spelling-based rule misses; with no
  *     client at all every such reference is a finding that says the repository has no client;
- *   - axios is imported only by the api owner (modules/api, the api package) for its rest calls and by the auth door
- *     (modules/auth/auth-door.ts) for the app's own auth doors; every other HTTP library is a
+ *   - axios is imported only by the api owner (modules/api, the api package) for its rest calls; every other HTTP library is a
  *     second transport wherever it is imported, by static import, `import()` or `require()`;
  *   - an `ApolloClient` is constructed only inside the client folder;
  *   - every GraphQL operation (`graphql/queries/query-*.ts`, `graphql/mutations/mutation-*.ts`, `graphql/subscriptions/subscription-*.ts`) imports the client (or the api

package/runtime/scripts/hfs/architecture/transport-owner.mjs

@@ -17,8 +17,7 @@ import { propertyValue } from './function-spec-providers.mjs';
  *   - no file outside the client folder and the stream reader folder (`fe.transport.stream`, `modules/api/sse/clients/`) references the global `fetch`: a call, `globalThis.fetch`, `window.fetch`, or a
  *     reference passed as a value (`useSWR(key, fetch)`, `const send = fetch`), all of which a spelling-based rule misses; with no
  *     client at all every such reference is a finding that says the repository has no client;
- *   - axios is imported only by the api owner (modules/api, the api package) for its rest calls and by the auth door
- *     (modules/auth/auth-door.ts) for the app's own auth doors; every other HTTP library is a
+ *   - axios is imported only by the api owner (modules/api, the api package) for its rest calls; every other HTTP library is a
  *     second transport wherever it is imported, by static import, `import()` or `require()`;
  *   - an `ApolloClient` is constructed only inside the client folder;
  *   - every GraphQL operation (`graphql/queries/query-*.ts`, `graphql/mutations/mutation-*.ts`, `graphql/subscriptions/subscription-*.ts`) imports the client (or the api
@@ -105,17 +104,15 @@ function isApolloClientConstruction(ts, kit, checker, node) {
     const binding = kit.importBinding(checker, node.expression);
     return Boolean(binding?.name === 'ApolloClient' && binding.module.startsWith('@apollo/client'));
 }
-/** The one auth door of the session issuer's client (`modules/auth/auth-door.ts`, slot fe.modules.auth): it calls the app's own auth doors with axios. */
-const isAuthDoor = (file) => file.slot === 'fe.modules.auth' && path.posix.basename(file.rel) === 'auth-door.ts';
 function inspectLibraryImport({ ts, file, node, transport, report }) {
     const specifier = moduleSpecifierOf(ts, node);
     if (!specifier || !ts.isStringLiteralLike(specifier))
         return;
     const library = specifier.text.split('/')[0];
-    if (!HTTP_LIBRARIES.has(library) || (library === REST_LIBRARY && (API_OWNER_SLOTS.has(file.slot) || isAuthDoor(file))))
+    if (!HTTP_LIBRARIES.has(library) || (library === REST_LIBRARY && (API_OWNER_SLOTS.has(file.slot))))
         return;
     const where = library === REST_LIBRARY
-        ? 'axios belongs to the api owner (modules/api/rest, the api package) and the auth door (modules/auth/auth-door.ts) only: call their functions'
+        ? 'axios belongs to the api owner (modules/api/rest, the api package) only: call their functions'
         : `the transport is Apollo GraphQL (${transport}) with axios for the rest calls of modules/api/rest`;
     report(file, node, `${specifier.text} is a second HTTP transport in ${file.rel}; ${where}.`, { library: specifier.text });
 }

package/runtime/scripts/hfs/manifest-shape.d.mts

@@ -64,6 +64,7 @@ export interface Slot {
     role?: string;
     importedBy?: string[];
     rewrittenBy?: string;
+    managedOnly?: boolean;
     logic?: string[];
     generatedBy?: string;
 }

package/runtime/scripts/hfs/manifest-shape.mjs

@@ -121,7 +121,7 @@ export const MANIFEST_KINDS = [APP_KIND, RUNTIME_KIND];
 /** The kind of a parsed manifest: `kind`, or app when absent (knowledge/hfs/slots.yaml carries none). */
 export const manifestKind = (m) => (isPlainObject(m) && m.kind !== undefined ? m.kind : APP_KIND);
 const strList = (v) => stringList(v);
-const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy', 'role', 'importedBy', 'rewrittenBy', 'logic'];
+const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy', 'role', 'importedBy', 'rewrittenBy', 'logic', 'managedOnly'];
 /** The roles a file slot may play that a rule reads (`role`): the entity registry of persistence.md BE-PERSISTENCE-3 (architecture/entity-registry.mjs). */
 const SLOT_ROLES = ['entity-registry'];
 /** The fields a slot's `lite` overlay may hold: the same keys it would carry in the slot body, resolved under edition lite. */
@@ -235,6 +235,8 @@ function slotListProblems(slot, at) {
         bad.push(`${at}: composedBy must be a non-empty list of unique app kinds`);
     if (slot.budget !== undefined && !budgetValid(slot.budget))
         bad.push(`${at}: budget must map names to positive integers`);
+    if (slot.managedOnly !== undefined && (slot.managedOnly !== true || slot.managedBy === undefined))
+        bad.push(`${at}: managedOnly is true and needs managedBy: the slot only lists files sync renders, and the slot owning the path judges them`);
     for (const key of ['managedBy', 'liteManagedBy'])
         if (slot[key] !== undefined && !NAME.test(String(slot[key])))
             bad.push(`${at}: ${key} must be a template id`);

package/runtime/scripts/hfs/rules/a15-findings.mjs

@@ -33,6 +33,8 @@ import { stacksIngressFindings } from './stacks-ingress.mjs';
 import { stacksLiteBackingFindings } from './stacks-lite-backing.mjs';
 import { stackToolingFindings } from './stack-tooling.mjs';
 import { stacksDeployFindings } from './stacks-deploy.mjs';
+import { stacksLocalFindings } from './stacks-local.mjs';
+import { stacksServiceImageFindings } from './stacks-service-images.mjs';
 import { stacksAuthCookieDomainFindings } from './stacks-auth-cookie-domain.mjs';
 import { ciCustodyFindings } from './ci-custody.mjs';
 import { workflowContextsFindings } from './workflow-contexts.mjs';
@@ -49,6 +51,7 @@ export const A15_CODES = [
     'HFS_WORKFLOW_CONTEXT',
     'CI_STANDARD',
     'CI_SECRET_SEALED', 'APP_SECRET_IN_CI', 'CI_DECLARATION_DRIFT',
+    'STACKS_LOCAL_CONFIG_INVALID', 'STACKS_DEV_UNDECLARED', 'STACKS_RUNBOOK_DOCKER_COMMAND',
     'BACKUP_PROOF_MISSING', 'BACKUP_UNDECLARED', 'BE_APP_BOOT_PROOF_MISSING', 'BOOT_PROOF_TIMEOUT', 'BE_APP_ENV_REQUIRED', 'BE_APP_MODULE_LIST_INLINE', 'BE_LITE_PROOF_LANE_MISSING', 'DB_ARCHIVE_MUTATED', 'DB_BASELINE_SHAPE', 'DB_EXTENSION_ALLOWED', 'DB_MIGRATION_DESTRUCTIVE', 'DB_PGMQ_DECLARED', 'DB_VAULT_WRITE', 'ENV_DUPLICATE', 'ENV_EXAMPLE_DRIFT', 'ENV_PUBLIC_SEALED', 'ENV_REQUIRED_UNSET', 'ENV_SEALED_UNREAD', 'ENV_VALUE_SHAPE', 'FE_STACK_CORE_MISSING', 'FE_STACK_UNLISTED', 'HFS_AGE_KEY_CUSTODY', 'HFS_APP_LEXICON', 'HFS_APP_WORKFLOW_TRIGGER', 'HFS_ASSET_KIND', 'HFS_ASSET_OVERSIZE', 'HFS_AUDIT_STEP_MISSING', 'HFS_AUTH_COOKIE_DOMAIN_MISSING', 'HFS_CANON_COPY_DRIFT', 'HFS_CI_TOOL_INSTALL', 'HFS_COVERAGE_BELOW', 'HFS_DB_DEPLOY_UNGUARDED', 'HFS_DEPENDABOT_MISSING', 'HFS_DEPLOY_COMPOSE_ON_VPS', 'HFS_DEPLOY_NO_LOGIC', 'HFS_DEPLOY_SCHEDULER', 'HFS_DEPLOY_WORKFLOW', 'HFS_DOC_COMMAND_UNKNOWN', 'HFS_DOC_ENV_UNKNOWN', 'HFS_DOC_PATH_MISSING', 'HFS_DOC_RULE_UNKNOWN', 'HFS_FEATURE_FILE_BUDGET', 'HFS_HOST_CRON', 'HFS_RELEASE_TAG_MISMATCH', 'HFS_SBOM_MISSING', 'HFS_SCHEDULE_UNDECLARED', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'HFS_SCRIPT_XTRACE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SEED_PII', 'HFS_UNUSED_SYMBOL', 'HFS_WORKFLOW_PIN', 'STACKS_DEPLOY_CONFIG_INVALID', 'STACKS_DNS_UNDECLARED', 'STACKS_HEALTHCHECK_MISSING', 'STACKS_HOST_UNROUTED', 'STACKS_INGRESS_UNDECLARED', 'STACKS_INGRESS_UNKNOWN', 'STACKS_LITE_REDIS_PERSISTENCE', 'STACKS_LITE_SELFHOSTED_DB', 'STACKS_MODEL_UNAVAILABLE', 'STACKS_PLACEMENT_MISSING', 'STACKS_PORT_PUBLISHED', 'STACKS_REALTIME_SCALED', 'STACKS_RELEASE_UNDECLARED', 'STACKS_SECOND_INGRESS', 'STACKS_SECRET_ENV_LITERAL', 'STACKS_SECRET_NOT_EXTERNAL', 'STACKS_SECRET_UNVERSIONED', 'STACKS_SIDECAR_DB_UNSUPPORTED', 'STACKS_SIDECAR_VOLUME_UNDECLARED', 'STACKS_TLS_UNDECLARED', 'STACKS_UPDATE_POLICY_MISSING', 'STACK_TOOLING_REIMPLEMENTED',
     // codes-end
 ];
@@ -87,6 +90,8 @@ export const FINDERS = [
     stacksLiteBackingFindings,
     stackToolingFindings,
     stacksDeployFindings,
+    stacksLocalFindings,
+    stacksServiceImageFindings,
     stacksAuthCookieDomainFindings,
     ciCustodyFindings,
     // finders-end

package/runtime/scripts/hfs/rules/stacks-local.d.mts

@@ -0,0 +1,7 @@
+import type { Repo } from './rule-types.mjs';
+/** Findings of the dev environments of the app root. */
+export declare function stacksLocalFindings({ repoRoot, repo, isRoot }: {
+    repoRoot: string;
+    repo: Repo;
+    isRoot: boolean;
+}): import("./rule-types.mjs").Finding[];

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

@@ -0,0 +1,71 @@
+// stacks-local.mjs - R372 and R373: the dev environment of an app is declared runnable and its runbook names the harness verb.
+//   R372 STACKS_LOCAL_CONFIG_INVALID  every docker-compose environment carries a `local` block that the dev verbs of `starci app stack`
+//                                      normalise (scripts/hfs/stack-local-config.mjs), and its compose services exist in the compose files;
+//        STACKS_DEV_UNDECLARED         a lite app declares at least one docker-compose environment (the dev kind of PROJECT-STACKS-3).
+//   R373 STACKS_RUNBOOK_DOCKER_COMMAND the runbook of a docker-compose environment names `starci app stack up --env <env>` and carries no
+//                                      `docker build|run|compose|create|start|stop|pull|push` or `docker stack deploy` command (rules.md rule 8).
+import fs from 'node:fs';
+import path from 'node:path';
+import { isPlainObject as plain } from '../../../engine/plain-object.mjs';
+import { findStackDeclaration, readDeclaration, STACK_ROOT } from '../../lib/stack-declaration.mjs';
+import { normalizeLocal } from '../stack-local-config.mjs';
+import { found, readJson } from './read.mjs';
+const DECLARATION = `${STACK_ROOT}/application-stacks.yaml`;
+const ENV_NAME = /^[a-z0-9][a-z0-9-]*$/u;
+const DOCKER_COMMAND = /^\s*(?:[$>]\s*)?(?:\w+=\S+\s+)*docker(?:-compose)?\s+(?:build|buildx|run|compose|create|start|stop|rm|pull|push|stack\s+deploy|stack\s+rm|service)\b/u;
+const mapping = (value) => (plain(value) ? value : {});
+function composeServices(envDir, spec) {
+    const names = new Set();
+    for (const relative of Array.isArray(spec.composeFiles) ? spec.composeFiles : []) {
+        if (typeof relative !== 'string' || path.isAbsolute(relative) || relative.split(/[\\/]/u).includes('..'))
+            continue;
+        for (const name of Object.keys(mapping(readDeclaration(path.join(envDir, relative)).doc?.services)))
+            names.add(name);
+    }
+    return names;
+}
+function localFindings({ repoRoot, project, environment, spec }) {
+    const at = `environments.${environment}.local`;
+    if (spec.local === undefined)
+        return [found('STACKS_LOCAL_CONFIG_INVALID', DECLARATION, `environments.${environment} runs docker-compose and declares no local block: declare the ports, services, processes and probes \`starci app stack up --env ${environment}\` runs`)];
+    const { config, problems } = normalizeLocal(spec.local, { project, env: environment });
+    const findings = problems.map((problem) => found('STACKS_LOCAL_CONFIG_INVALID', DECLARATION, `${at}.${problem.at}: ${problem.message}`));
+    if (config) {
+        const services = composeServices(path.join(repoRoot, STACK_ROOT, environment), spec);
+        for (const service of config.services)
+            if (!services.has(service.name))
+                findings.push(found('STACKS_LOCAL_CONFIG_INVALID', DECLARATION, `${at}.services: ${service.name} is not a service of the compose files of ${environment}`));
+    }
+    return findings;
+}
+function runbookFindings({ repoRoot, environment, spec }) {
+    const relative = typeof spec.runbook === 'string' ? spec.runbook : 'README.md';
+    const file = path.join(repoRoot, STACK_ROOT, environment, relative);
+    const display = path.relative(repoRoot, file).split(path.sep).join('/');
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const findings = text.split(/\r?\n/u).map((line, index) => ({ line, index })).filter(({ line }) => DOCKER_COMMAND.test(line) || /`docker\s+(?:build|run|compose|create|start|stop|pull|push|stack)\b/u.test(line))
+        .map(({ index }) => found('STACKS_RUNBOOK_DOCKER_COMMAND', `${display}:${index + 1}`, `the runbook of ${environment} carries a docker command; Docker is run by the harness: name \`starci app stack up --env ${environment}\` instead`));
+    if (!text.includes(`starci app stack up --env ${environment}`))
+        findings.push(found('STACKS_RUNBOOK_DOCKER_COMMAND', display, `the runbook of ${environment} does not name \`starci app stack up --env ${environment}\`, the one command that brings the environment up`));
+    return findings;
+}
+/** Findings of the dev environments of the app root. */
+export function stacksLocalFindings({ repoRoot, repo, isRoot }) {
+    if (repo?.kind !== 'app' || !['lite', 'full'].some((value) => value === repo.edition) || isRoot === false)
+        return [];
+    const { doc } = findStackDeclaration(repoRoot);
+    if (!doc)
+        return [];
+    const project = String(readJson(repoRoot, 'hfs.json')?.project ?? 'app');
+    const judged = Object.entries(mapping(mapping(doc).environments)).filter(([environment, spec]) => ENV_NAME.test(environment) && plain(spec) && spec.runtime === 'docker-compose');
+    const findings = judged.flatMap(([environment, spec]) => [...localFindings({ repoRoot, project, environment, spec }), ...runbookFindings({ repoRoot, environment, spec })]);
+    if (repo.edition === 'lite' && judged.length === 0)
+        findings.push(found('STACKS_DEV_UNDECLARED', DECLARATION, 'a lite app declares its dev environment: an environment with runtime docker-compose and a local block, run by `starci app stack up --env dev` (PROJECT-STACKS-3, PROJECT-STACKS-6)'));
+    return findings;
+}

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

@@ -99,6 +99,9 @@ function liteEnvironmentFindings({ doc, environments, deployments }) {
     for (const [environment, spec] of Object.entries(environments)) {
         if (!Array.isArray(spec?.composeFiles) || !spec.composeFiles.length)
             continue;
+        // The dev kind (PROJECT-STACKS-3): docker-compose sources under infra/compose/ with the local block `starci app stack up` runs; judged by R372.
+        if (spec.runtime === 'docker-compose' && spec.local !== undefined && spec.composeFiles.every((file) => typeof file === 'string' && file.startsWith('infra/compose/')))
+            continue;
         if (spec.runtime !== 'docker-swarm' || spec.composeFiles.some((file) => typeof file !== 'string' || !file.startsWith('infra/swarm/')))
             findings.push(found(CODE, DECLARATION, `${DECLARATION}: environments.${environment} lite delivery must use runtime: docker-swarm and infra/swarm sources`));
     }
@@ -111,11 +114,13 @@ function undeclaredSwarmFindings(deployments, environments, sources) {
         return found(CODE, file, `${file}: Swarm deployment ${reason}`);
     });
 }
+/** The component ids a docker-swarm environment binds: the only ones the lite refusal of backing images judges (a dev compose environment runs its own MinIO, Redis and agent runtime). */
+const swarmBoundComponents = (environments) => new Set(Object.values(environments).filter((spec) => spec?.runtime === 'docker-swarm').flatMap((spec) => Object.keys(mapping(spec.components))));
 /** Declared Swarm sources are checked for both editions; lite additionally refuses local managed backing images. */
 export function stacksRuntimeFindings({ repoRoot, files, doc, edition = 'full' }) {
     const findings = [], lite = edition === 'lite', components = mapping(doc?.components), environments = mapping(doc?.environments);
     const deployments = swarmDeploymentFiles(repoRoot, files), sources = new Set();
-    findings.push(...swarmInventoryIssues({ components, lite }).map((issue) => issueFinding(DECLARATION, issue)));
+    findings.push(...swarmInventoryIssues({ components, lite, swarm: swarmBoundComponents(environments) }).map((issue) => issueFinding(DECLARATION, issue)));
     if (lite)
         findings.push(...liteEnvironmentFindings({ doc, environments, deployments }));
     for (const [environment, entry] of Object.entries(environments)) {

package/runtime/scripts/hfs/rules/stacks-service-images.d.mts

@@ -0,0 +1,12 @@
+import { found } from './read.mjs';
+import type { Repo } from './rule-types.mjs';
+type Finding = ReturnType<typeof found>;
+/** The fork repositories the harness owns, by service name. */
+export declare function forkImages(): Record<string, string>;
+/** Findings of R374 for the app root. */
+export declare function stacksServiceImageFindings({ repoRoot, repo, isRoot }: {
+    repoRoot: string;
+    repo: Repo;
+    isRoot: boolean;
+}): Finding[];
+export {};

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

@@ -0,0 +1,120 @@
+// stacks-service-images.mjs - R374: a customised service runs from an image the app builds, never from an upstream image with code mounted into it.
+//   STACKS_CODE_BIND_MOUNT      a stack or compose file bind-mounts code, a script, a plugin or a writable repository path into a service container.
+//                               Allowed: a named volume, a secret or config grant (not volumes), a bind under the data root (`${data}`, `${STACK_DATA_DIR}`) or a least grant (`${STACK_GRANT_<NAME>}`),
+//                               the docker socket read-only, and a read-only plain data file (json, yaml, toml, conf, ini, properties, txt, pem, crt, csv).
+//   STACKS_IMAGE_BASE_UNPINNED  a Dockerfile of `.starcistacks/images/<name>/` has a FROM that is not digest-pinned.
+//   STACKS_IMAGE_BASE_NOT_FORK  the image folder of a service the harness owns a fork image for (knowledge/hfs/fork-images.yaml) does not end FROM that fork.
+//   STACKS_IMAGE_ENV_DIVERGES   a service that has an image folder runs a literal third-party image in some environment: every environment runs the
+//                               image built from the folder (compose `build.context`, or a project-owned or variable image reference), so dev and production share it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { isPlainObject as plain } from '../../../engine/plain-object.mjs';
+import { parseYaml } from '../../../engine/yaml.mjs';
+import { findStackDeclaration, readDeclaration, STACK_ROOT } from '../../lib/stack-declaration.mjs';
+import { found, readJson } from './read.mjs';
+const FORKS = new URL('../../../knowledge/hfs/fork-images.yaml', import.meta.url);
+const ENV_NAME = /^[a-z0-9][a-z0-9-]*$/u;
+const DATA_ROOT = /^(?:\$\{(?:data|STACK_DATA_DIR|STACK_GRANT_[A-Z0-9_]+)\}|\$(?:data|STACK_DATA_DIR|STACK_GRANT_[A-Z0-9_]+))(?:[\\/]|$)/u;
+const DATA_FILE = /\.(?:json|ya?ml|toml|conf|cnf|cfg|ini|properties|txt|pem|crt|csv)$/iu;
+const SOCKET = '/var/run/docker.sock';
+const mapping = (value) => (plain(value) ? value : {});
+/** The fork repositories the harness owns, by service name. */
+export function forkImages() {
+    return mapping(mapping(parseYaml(fs.readFileSync(FORKS, 'utf8'))).images);
+}
+/** One volume entry as { source, readOnly } when it is a bind mount (a host path), else null. */
+function bindOf(entry) {
+    if (typeof entry === 'string') {
+        const [source = '', , mode = ''] = entry.split(':');
+        if (!/^(?:\.|\/|~|\$\{|\$[A-Za-z])/u.test(source))
+            return null;
+        return { source, readOnly: mode.split(',').includes('ro') };
+    }
+    const long = mapping(entry);
+    if (long.type !== 'bind' || typeof long.source !== 'string')
+        return null;
+    return { source: long.source, readOnly: long.read_only === true };
+}
+/** Whether a bind mount is a data volume or plain read-only config data, the line R374 draws. */
+const allowedBind = ({ source, readOnly }) => DATA_ROOT.test(source) || (readOnly && (source === SOCKET || DATA_FILE.test(source)));
+const baseOf = (reference) => reference.replace(/@sha256:[0-9a-f]+$/iu, '').replace(/:[^/:]+$/u, '');
+function bindFindings(display, environment, services) {
+    return Object.entries(services).flatMap(([name, service]) => (Array.isArray(mapping(service).volumes) ? mapping(service).volumes : [])
+        .map(bindOf).filter((bind) => bind !== null && !allowedBind(bind))
+        .map((bind) => found('STACKS_CODE_BIND_MOUNT', display, `${environment}: service ${name} bind-mounts ${bind.source}; code, plugins and scripts are baked into an image built from .starcistacks/images/${name}/ (FROM the pinned base, or the harness fork image), and only data volumes, secrets and read-only plain config data are mounted`)));
+}
+function dockerfileFindings(repoRoot, forks) {
+    const images = path.join(repoRoot, STACK_ROOT, 'images');
+    if (!fs.existsSync(images))
+        return [];
+    return fs.readdirSync(images, { withFileTypes: true }).filter((entry) => entry.isDirectory()).flatMap((entry) => {
+        const display = `${STACK_ROOT}/images/${entry.name}/Dockerfile`;
+        let text;
+        try {
+            text = fs.readFileSync(path.join(images, entry.name, 'Dockerfile'), 'utf8');
+        }
+        catch {
+            return [];
+        }
+        const stages = new Set();
+        const bases = [];
+        const findings = [];
+        for (const line of text.split(/\r?\n/u)) {
+            const from = /^\s*FROM\s+(?:--platform=\S+\s+)?(\S+)(?:\s+AS\s+(\S+))?/iu.exec(line);
+            if (!from)
+                continue;
+            const ref = from[1];
+            if (from[2])
+                stages.add(from[2].toLowerCase());
+            if (stages.has(ref.toLowerCase()) || ref === 'scratch')
+                continue;
+            bases.push(ref);
+            if (!/@sha256:[0-9a-f]{64}/iu.test(ref))
+                findings.push(found('STACKS_IMAGE_BASE_UNPINNED', display, `FROM ${ref} is not pinned by digest (name@sha256:...)`));
+        }
+        const fork = forks[entry.name];
+        const last = bases.at(-1);
+        if (fork !== undefined && last !== undefined && baseOf(last) !== fork)
+            findings.push(found('STACKS_IMAGE_BASE_NOT_FORK', display, `the harness owns the StarCi fork image ${fork} for ${entry.name}; the final stage must be FROM ${fork}@sha256:..., not ${baseOf(last)}`));
+        return findings;
+    });
+}
+/** Whether a service's image/build is the one built from its image folder, or a project-owned or variable reference. */
+function builtFromFolder(service, name, project) {
+    const build = service.build;
+    const context = typeof build === 'string' ? build : typeof mapping(build).context === 'string' ? String(mapping(build).context) : '';
+    if (context !== '' && context.replaceAll('\\', '/').includes(`images/${name}`))
+        return true;
+    const image = typeof service.image === 'string' ? service.image : '';
+    return image.includes('${') || image.startsWith(`${project}/`) || image.startsWith(`${project}-`) || image.includes(`/${project}/`);
+}
+/** Findings of R374 for the app root. */
+export function stacksServiceImageFindings({ repoRoot, repo, isRoot }) {
+    if (repo?.kind !== 'app' || !['lite', 'full'].some((value) => value === repo.edition) || isRoot === false)
+        return [];
+    const { doc } = findStackDeclaration(repoRoot);
+    if (!doc)
+        return [];
+    const project = String(readJson(repoRoot, 'hfs.json')?.project ?? 'app');
+    const folders = path.join(repoRoot, STACK_ROOT, 'images');
+    const withFolder = new Set(fs.existsSync(folders) ? fs.readdirSync(folders, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name) : []);
+    const findings = dockerfileFindings(repoRoot, forkImages());
+    for (const [environment, spec] of Object.entries(mapping(mapping(doc).environments))) {
+        if (!ENV_NAME.test(environment) || !plain(spec))
+            continue;
+        const files = Array.isArray(spec.composeFiles) ? spec.composeFiles : [];
+        for (const relative of files) {
+            if (typeof relative !== 'string' || path.isAbsolute(relative) || relative.split(/[\\/]/u).includes('..'))
+                continue;
+            const file = path.join(repoRoot, STACK_ROOT, environment, relative);
+            const display = path.relative(repoRoot, file).split(path.sep).join('/');
+            const services = mapping(readDeclaration(file).doc?.services);
+            findings.push(...bindFindings(display, environment, services));
+            for (const [name, service] of Object.entries(services)) {
+                if (withFolder.has(name) && !builtFromFolder(mapping(service), name, project))
+                    findings.push(found('STACKS_IMAGE_ENV_DIVERGES', display, `${environment}: service ${name} has an image folder but runs ${String(mapping(service).image)}; every environment runs the image built from .starcistacks/images/${name}/ so dev and production share one image`));
+            }
+        }
+    }
+    return findings;
+}

package/runtime/scripts/hfs/secret-dev-init.d.mts

@@ -0,0 +1,11 @@
+import type { SecretSops } from "./secret-sops.mjs";
+import type { CustodyGenerator } from "./stack-local-config.mjs";
+/** One generated value (or a private/public pair) by its kind; the `password` kind is URL- and SQL-safe. */
+export declare function generateValues(entry: CustodyGenerator, random?: (bytes: number) => Buffer): Record<string, string>;
+/** Seals the missing dev values of `environment`; a dry run unless `execute`. Returns the exit code. */
+export declare function seedDevCustody(repoRoot: string, environment: string, { execute, sops, stdout, random }: {
+    execute: boolean;
+    sops: () => SecretSops;
+    stdout: (text: string) => unknown;
+    random?: (bytes: number) => Buffer;
+}): number;

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

@@ -0,0 +1,79 @@
+// secret-dev-init.mjs - `starci app secret init --env <dev env> [--execute]`: creates the dev-only values the environment's `local.custody`
+// declares (PROJECT-STACKS-5: sealed only, owner-armed, created once, never replaced). It refuses an environment that is not a docker-compose
+// dev environment (vps and production never get generated values), skips a key its member already holds, and refuses a half-present pair
+// instead of minting a replacement. Values are generated in memory and sealed in one write per member; names are all it prints.
+import fs from "node:fs";
+import { generateKeyPairSync, randomBytes, randomUUID } from "node:crypto";
+import { envelopeOf } from "./secret-document.mjs";
+import { SecretError } from "./secret-errors.mjs";
+import { fileOf, secretsDirectory, writeSecret } from "./secret-store.mjs";
+import { declareKeys } from "./secret-standard.mjs";
+import { isLocalEnvironment, loadLocalConfig } from "../../../stack/local-config.mjs";
+/** One generated value (or a private/public pair) by its kind; the `password` kind is URL- and SQL-safe. */
+export function generateValues(entry, random = randomBytes) {
+    if (entry.kind === "hex")
+        return { [entry.key]: random(entry.bytes).toString("hex") };
+    if (entry.kind === "base64")
+        return { [entry.key]: random(entry.bytes).toString("base64") };
+    if (entry.kind === "password")
+        return { [entry.key]: random(entry.bytes).toString("base64url") };
+    if (entry.kind === "uuid")
+        return { [entry.key]: randomUUID() };
+    if (entry.kind === "rsa-pem" || entry.kind === "ec-pem" || entry.kind === "ed25519-pem") {
+        const pair = entry.kind === "rsa-pem"
+            ? generateKeyPairSync("rsa", { modulusLength: 2048, privateKeyEncoding: { type: "pkcs8", format: "pem" }, publicKeyEncoding: { type: "spki", format: "pem" } })
+            : entry.kind === "ec-pem"
+                ? generateKeyPairSync("ec", { namedCurve: "P-256", privateKeyEncoding: { type: "pkcs8", format: "pem" }, publicKeyEncoding: { type: "spki", format: "pem" } })
+                : generateKeyPairSync("ed25519", { privateKeyEncoding: { type: "pkcs8", format: "pem" }, publicKeyEncoding: { type: "spki", format: "pem" } });
+        return { [entry.key]: pair.privateKey, ...(entry.publicKey ? { [entry.publicKey]: pair.publicKey } : {}) };
+    }
+    throw new SecretError(`the generator ${entry.kind} is unknown`);
+}
+/** Seals the missing dev values of `environment`; a dry run unless `execute`. Returns the exit code. */
+export function seedDevCustody(repoRoot, environment, { execute, sops, stdout, random = randomBytes }) {
+    if (!isLocalEnvironment(repoRoot, environment))
+        throw new SecretError(`secret init --env ${environment}: only a docker-compose dev environment gets generated values; a vps or production value is set by the owner with secret set (PROJECT-STACKS-5)`);
+    const local = loadLocalConfig({ repoRoot, env: environment });
+    if (local.custody.length === 0)
+        throw new SecretError(`environment ${environment} declares no local.custody: nothing to generate; the owner seals its values with secret set`);
+    const directory = secretsDirectory(repoRoot, environment);
+    const byMember = new Map();
+    for (const entry of local.custody)
+        byMember.set(entry.member, [...(byMember.get(entry.member) ?? []), entry]);
+    const writes = [];
+    for (const [member, entries] of byMember) {
+        const file = fileOf(directory, member);
+        const held = fs.existsSync(file) ? envelopeOf(fs.readFileSync(file, "utf8")).keys : [];
+        const values = {};
+        for (const entry of entries) {
+            const names = [entry.key, ...(entry.publicKey ? [entry.publicKey] : [])];
+            const have = names.filter((name) => held.includes(name));
+            if (have.length === names.length) {
+                stdout(`kept ${environment}/${member} ${entry.key} (already sealed, never replaced)\n`);
+                continue;
+            }
+            if (have.length > 0)
+                throw new SecretError(`${environment}/${member} holds ${have.join(", ")} but not the rest of its pair ${names.join(", ")}: a replacement is never minted for an existing sealed value; the owner removes the pair with secret unset and runs init again`);
+            Object.assign(values, generateValues(entry, random));
+        }
+        if (Object.keys(values).length)
+            writes.push({ file, member, values });
+    }
+    for (const write of writes) {
+        const names = Object.keys(write.values);
+        if (!execute) {
+            stdout(`would seal ${environment}/${write.member} (${names.join(", ")})\n`);
+            continue;
+        }
+        writeSecret({ file: write.file, values: write.values, age: [], sops: sops() });
+        stdout(`sealed ${environment}/${write.member} (${names.join(", ")})\n`);
+        const declaration = declareKeys(repoRoot, environment, write.member, names);
+        if (declaration.declared.length)
+            stdout(`declared ${declaration.declared.join(", ")} in environments.${environment}.secrets of application-stacks.yaml\n`);
+    }
+    if (writes.length === 0)
+        stdout("nothing to create: every declared dev value is sealed\n");
+    else if (!execute)
+        stdout("dry run: nothing was written; arm it with --execute (the owner's yes)\n");
+    return 0;
+}