@starci/hfs 4.11.21 → 4.12.0

package/runtime/scripts/hfs/rules/stacks-auth-cookie-domain.mjs

@@ -0,0 +1,149 @@
+// stacks-auth-cookie-domain.mjs - R337 HFS_AUTH_COOKIE_DOMAIN_MISSING: the api's refresh cookie reaches the web server.
+// The lite skeleton's passport sets its refresh cookie host-only on the api host unless `AUTH_COOKIE_DOMAIN` is set. When the web
+// is served on app.<domain> and the api on api.<domain>, the web server forwards the browser's Cookie header to the api, and a
+// host-only api cookie is not in it: the api refuses the session and the user loops back to sign-in.
+//   Judged: a docker-swarm environment of an app whose api uses the skeleton's passport (the lite edition, a tracked
+//   `.../src/modules/integrations/passport/passport.config.ts`) and whose rendered stack has the `api` and `web` services.
+//   The hosts are read from the rendered stack of the environment, first match wins:
+//     web  = web NEXT_PUBLIC_SITE_URL, AUTH_WEB_ORIGIN (api or web), the `deploy.verify.http` url named web, the api's first
+//            HTTP_SECURITY_ALLOWED_ORIGINS origin;
+//     api  = api AUTH_JWT_ISSUER, api GOOGLE_CALLBACK_URL, web NEXT_PUBLIC_API_URL, the `deploy.verify.http` url named api.
+//   An unknown host is not judged. Ports are ignored (a cookie is scoped to a host, not a port).
+//   Findings (error): different hosts and no AUTH_COOKIE_DOMAIN (declared by the api's stack environment, listed in the
+//   environment's KEYS.md, or sealed under its secrets/); a declared AUTH_COOKIE_DOMAIN that is not a bare domain or is not a
+//   parent of the hosts. Limit: no public-suffix list is read, only the common `co.uk` style second-level suffixes are refused.
+import { isPlainObject as plain } from '../../../engine/plain-object.mjs';
+import { envelopeOf } from '../secret-document.mjs';
+import { readText } from './read.mjs';
+import { stacksDeploymentFindings } from './stacks-runtime.mjs';
+export const HFS_AUTH_COOKIE_DOMAIN_MISSING = 'HFS_AUTH_COOKIE_DOMAIN_MISSING';
+export const AUTH_COOKIE_DOMAIN = 'AUTH_COOKIE_DOMAIN';
+const PASSPORT_CONFIG = /(?:^|\/)src\/modules\/integrations\/passport\/passport\.config\.ts$/u;
+const BARE_DOMAIN = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,61}[a-z0-9]$/u;
+const SECOND_LEVEL_SUFFIX = /^(?:ac|co|com|edu|gov|net|org)\.[a-z]{2}$/u;
+const SEALED_MEMBER = /^\.starcistacks\/([^/]+)\/secrets\/[^/]+\.enc(?:\.yaml)?$/u;
+const ENV_ASSIGNMENT = /^([A-Za-z_]\w*)=(.*)$/su;
+const dict = (value) => (plain(value) ? value : {});
+const list = (value) => (Array.isArray(value) ? value : []);
+const text = (value) => (typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined);
+/** The environment of one rendered service as name to value; both the mapping and the `K=V` list forms. */
+function environmentOf(service) {
+    const raw = dict(service).environment, out = {};
+    if (Array.isArray(raw)) {
+        for (const entry of raw) {
+            const match = typeof entry === 'string' ? ENV_ASSIGNMENT.exec(entry) : null;
+            if (match?.[1] !== undefined)
+                out[match[1]] = match[2] ?? '';
+        }
+        return out;
+    }
+    for (const [name, value] of Object.entries(dict(raw)))
+        if (value !== null && value !== undefined)
+            out[name] = String(value);
+    return out;
+}
+/** The lower-case host name of an origin or URL text (first entry of a comma list), or undefined. */
+function hostOfOrigin(value) {
+    const first = value?.split(',').map((part) => part.trim()).find((part) => part !== '');
+    if (first === undefined || !URL.canParse(first))
+        return undefined;
+    const host = new URL(first).hostname.toLowerCase();
+    return host === '' ? undefined : host;
+}
+const firstHost = (candidates) => {
+    for (const candidate of candidates) {
+        const host = hostOfOrigin(candidate);
+        if (host !== undefined)
+            return host;
+    }
+    return undefined;
+};
+/** The `deploy.verify.http` url of the entry whose name mentions `word`, or undefined. */
+function verifyUrl(spec, word) {
+    const entry = list(dict(dict(dict(spec).deploy).verify).http).find((candidate) => word.test(String(dict(candidate).name ?? '')));
+    return text(dict(entry).url);
+}
+/** The public hosts the environment declares for its web and its api; undefined when the stack does not state one. */
+export function publicHosts({ model, spec }) {
+    const services = dict(dict(model).services);
+    const api = environmentOf(services.api), web = environmentOf(services.web);
+    const webHost = firstHost([web.NEXT_PUBLIC_SITE_URL, api.AUTH_WEB_ORIGIN, web.AUTH_WEB_ORIGIN, verifyUrl(spec, /\bweb\b/iu), api.HTTP_SECURITY_ALLOWED_ORIGINS]);
+    const apiHost = firstHost([api.AUTH_JWT_ISSUER, api.GOOGLE_CALLBACK_URL, web.NEXT_PUBLIC_API_URL, verifyUrl(spec, /\bapi\b/iu)]);
+    return { ...(webHost === undefined ? {} : { web: webHost }), ...(apiHost === undefined ? {} : { api: apiHost }) };
+}
+/** The longest shared host suffix of at least two labels that is not a second-level public suffix, or undefined. */
+export function commonParentDomain(left, right) {
+    const a = left.split('.').reverse(), b = right.split('.').reverse(), shared = [];
+    for (let index = 0; index < Math.min(a.length, b.length) && a[index] === b[index]; index += 1)
+        shared.push(a[index]);
+    const domain = shared.reverse().join('.');
+    return shared.length >= 2 && BARE_DOMAIN.test(domain) && !SECOND_LEVEL_SUFFIX.test(domain) ? domain : undefined;
+}
+const isParentOf = (domain, host) => host === domain || host.endsWith(`.${domain}`);
+/** Whether the api's environment provides the key: a declared value, a KEYS.md row or a sealed member key. */
+function keyProvided({ environment, api, files, repoRoot }) {
+    if (AUTH_COOKIE_DOMAIN in api || `${AUTH_COOKIE_DOMAIN}_FILE` in api)
+        return true;
+    if (repoRoot === undefined)
+        return false;
+    const roster = `.starcistacks/${environment}/runtime/env/KEYS.md`;
+    if (files.includes(roster) && (readText(repoRoot, roster) ?? '').includes(`\`${AUTH_COOKIE_DOMAIN}\``))
+        return true;
+    return files.some((file) => {
+        if (SEALED_MEMBER.exec(file)?.[1] !== environment)
+            return false;
+        const sealed = readText(repoRoot, file);
+        if (sealed === null)
+            return false;
+        try {
+            return envelopeOf(sealed).keys.includes(AUTH_COOKIE_DOMAIN);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function declaredValueIssues(value, hosts, at) {
+    const domain = value.trim().toLowerCase();
+    const issue = (message) => [{ code: HFS_AUTH_COOKIE_DOMAIN_MISSING, at, message }];
+    if (!BARE_DOMAIN.test(domain))
+        return issue(`${AUTH_COOKIE_DOMAIN} must be a bare domain such as example.com (no scheme, port, path, leading dot or IP); the api refuses to boot on anything else`);
+    const outside = [hosts.web, hosts.api].filter((host) => host !== undefined && !isParentOf(domain, host));
+    if (outside.length === 0)
+        return [];
+    const parent = hosts.web !== undefined && hosts.api !== undefined ? commonParentDomain(hosts.web, hosts.api) : undefined;
+    return issue(`${AUTH_COOKIE_DOMAIN} is ${domain}, which is not a parent of ${outside.join(' and ')}; a browser drops a cookie whose Domain is not a parent of the host that sets it${parent === undefined ? '' : `; set it to ${parent}`}`);
+}
+/** The R337 issues of one rendered environment. `passport` says whether the api uses the skeleton's passport. */
+export function authCookieDomainIssues(input) {
+    if (!input.passport)
+        return [];
+    const services = dict(dict(input.model).services);
+    if (!plain(services.api) || !plain(services.web))
+        return [];
+    const hosts = publicHosts(input), api = environmentOf(services.api);
+    const at = `services.api.environment.${AUTH_COOKIE_DOMAIN}`;
+    const declared = text(api[AUTH_COOKIE_DOMAIN]);
+    if (declared !== undefined)
+        return declaredValueIssues(declared, hosts, at);
+    if (hosts.web === undefined || hosts.api === undefined || hosts.web === hosts.api)
+        return [];
+    if (keyProvided({ environment: input.environment, api, files: input.files, repoRoot: input.repoRoot }))
+        return [];
+    const parent = commonParentDomain(hosts.web, hosts.api);
+    const remedy = parent === undefined
+        ? 'they share no registrable parent domain, so the cookie cannot reach the web server; serve both under one domain'
+        : `set ${AUTH_COOKIE_DOMAIN}=${parent} in the api's environment (the stack environment, KEYS.md or a sealed key)`;
+    return [{ code: HFS_AUTH_COOKIE_DOMAIN_MISSING, at: `environments.${input.environment}`,
+            message: `the web is served on ${hosts.web} and the api on ${hosts.api}, so the api's refresh cookie is host-only on ${hosts.api} and is missing from the Cookie header the web server forwards (a login loop); ${remedy}` }];
+}
+/** HFS finder over the tracked rendered Swarm environments of the lite app root whose api uses the skeleton's passport. */
+export function stacksAuthCookieDomainFindings(context) {
+    if (context?.repo?.edition !== 'lite')
+        return [];
+    const files = context.all ?? context.files ?? [];
+    const passport = files.some((file) => PASSPORT_CONFIG.test(file));
+    if (!passport)
+        return [];
+    return stacksDeploymentFindings(context, (entry) => authCookieDomainIssues({ environment: entry.environment, spec: entry.spec, model: entry.model, files, repoRoot: context.repoRoot, passport }));
+}

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

@@ -0,0 +1,7 @@
+import type { Repo } from './rule-types.mjs';
+/** Findings of every declared deploy block of the app root, in both editions. */
+export declare function stacksDeployFindings({ repoRoot, repo, isRoot }: {
+    repoRoot: string;
+    repo: Repo;
+    isRoot: boolean;
+}): any[];

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

@@ -9,69 +9,59 @@ import { isPlainObject as plain } from '../../../engine/plain-object.mjs';
 import { findStackDeclaration, readDeclaration, STACK_ROOT } from '../../lib/stack-declaration.mjs';
 import { normalizeDeploy } from '../stack-deploy-config.mjs';
 import { found, readJson } from './read.mjs';
-
 const DECLARATION = `${STACK_ROOT}/application-stacks.yaml`;
 const ENV_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 const mapping = (value) => (plain(value) ? value : {});
-
 /** Service names of the first composeFiles entry; an unreadable stack source means unknown services (empty set). */
 function stackServices(envDir, spec) {
-  const relative = Array.isArray(spec.composeFiles) ? spec.composeFiles[0] : undefined;
-  if (typeof relative !== 'string' || path.isAbsolute(relative) || relative.split(/[\\/]/).includes('..')) return new Set();
-  const { doc } = readDeclaration(path.join(envDir, relative));
-  return new Set(Object.keys(mapping(doc?.services)));
+    const relative = Array.isArray(spec.composeFiles) ? spec.composeFiles[0] : undefined;
+    if (typeof relative !== 'string' || path.isAbsolute(relative) || relative.split(/[\\/]/).includes('..'))
+        return new Set();
+    const { doc } = readDeclaration(path.join(envDir, relative));
+    return new Set(Object.keys(mapping(doc?.services)));
 }
-
 function sealedMembers(envDir) {
-  try {
-    return new Set(fs.readdirSync(path.join(envDir, 'secrets')).filter(isSealedName).map(memberOfName));
-  } catch { return new Set(); }
+    try {
+        return new Set(fs.readdirSync(path.join(envDir, 'secrets')).filter(isSealedName).map(memberOfName));
+    }
+    catch {
+        return new Set();
+    }
 }
-
 function probeOf(envDir, spec) {
-  return { exists: (relative) => fs.existsSync(path.join(envDir, relative)), services: stackServices(envDir, spec), members: sealedMembers(envDir) };
+    return { exists: (relative) => fs.existsSync(path.join(envDir, relative)), services: stackServices(envDir, spec), members: sealedMembers(envDir) };
 }
-
 /** The shell scripts below the environment directory (node_modules aside), as absolute paths. */
 function shellScripts(directory) {
-  return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
-    const file = path.join(directory, entry.name);
-    if (entry.isDirectory()) return entry.name === 'node_modules' ? [] : shellScripts(file);
-    return entry.name.endsWith('.sh') ? [file] : [];
-  });
+    return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+        const file = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            return entry.name === 'node_modules' ? [] : shellScripts(file);
+        return entry.name.endsWith('.sh') ? [file] : [];
+    });
 }
-
 /** A shell script with CRLF line endings fails inside the container (`set: Illegal option -`): one finding per such file. */
 function lineEndingFindings({ repoRoot, envDir, environment }) {
-  if (!fs.existsSync(envDir)) return [];
-  const crlf = String.fromCodePoint(13, 10);
-  return shellScripts(envDir).filter((file) => fs.readFileSync(file, 'utf8').includes(crlf)).map((file) => found(
-    'STACKS_DEPLOY_CONFIG_INVALID',
-    path.relative(repoRoot, file).split(path.sep).join('/'),
-    `environments.${environment}: this shell script has CRLF line endings and fails in the container; commit it with LF (.gitattributes: *.sh text eol=lf) and save it again`,
-  ));
+    if (!fs.existsSync(envDir))
+        return [];
+    const crlf = String.fromCodePoint(13, 10);
+    return shellScripts(envDir).filter((file) => fs.readFileSync(file, 'utf8').includes(crlf)).map((file) => found('STACKS_DEPLOY_CONFIG_INVALID', path.relative(repoRoot, file).split(path.sep).join('/'), `environments.${environment}: this shell script has CRLF line endings and fails in the container; commit it with LF (.gitattributes: *.sh text eol=lf) and save it again`));
 }
-
 function environmentFindings({ repoRoot, project, environment, spec }) {
-  const envDir = path.join(repoRoot, STACK_ROOT, environment);
-  const { problems } = normalizeDeploy(spec.deploy, { project, probe: probeOf(envDir, spec) });
-  return [...problems.map((problem) => found(
-    'STACKS_DEPLOY_CONFIG_INVALID',
-    DECLARATION,
-    `environments.${environment}.${problem.at}: ${problem.message}`,
-  )), ...lineEndingFindings({ repoRoot, envDir, environment })];
+    const envDir = path.join(repoRoot, STACK_ROOT, environment);
+    const { problems } = normalizeDeploy(spec.deploy, { project, probe: probeOf(envDir, spec) });
+    return [...problems.map((problem) => found('STACKS_DEPLOY_CONFIG_INVALID', DECLARATION, `environments.${environment}.${problem.at}: ${problem.message}`)), ...lineEndingFindings({ repoRoot, envDir, environment })];
 }
-
 /** Only docker-swarm environments that declare a deploy block are judged. */
 function judged([environment, spec]) {
-  return ENV_NAME.test(environment) && plain(spec) && spec.runtime === 'docker-swarm' && spec.deploy !== undefined;
+    return ENV_NAME.test(environment) && plain(spec) && spec.runtime === 'docker-swarm' && spec.deploy !== undefined;
 }
-
 /** Findings of every declared deploy block of the app root, in both editions. */
 export function stacksDeployFindings({ repoRoot, repo, isRoot }) {
-  if (repo?.kind !== 'app' || !['lite', 'full'].includes(repo.edition) || isRoot === false) return [];
-  const { doc } = findStackDeclaration(repoRoot);
-  const project = String(readJson(repoRoot, 'hfs.json')?.project ?? 'app');
-  return Object.entries(mapping(mapping(doc).environments)).filter(judged)
-    .flatMap(([environment, spec]) => environmentFindings({ repoRoot, project, environment, spec }));
+    if (repo?.kind !== 'app' || !['lite', 'full'].some((value) => value === repo.edition) || isRoot === false)
+        return [];
+    const { doc } = findStackDeclaration(repoRoot);
+    const project = String(readJson(repoRoot, 'hfs.json')?.project ?? 'app');
+    return Object.entries(mapping(mapping(doc).environments)).filter(judged)
+        .flatMap(([environment, spec]) => environmentFindings({ repoRoot, project, environment, spec }));
 }

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

@@ -0,0 +1,16 @@
+import type { Parsed } from './rule-types.mjs';
+/** The name of the shared external ingress stack the environment declares, or null. */
+export declare const externalIngressStack: (spec: Parsed) => any;
+/** Static ingress contract shared by HFS and the rendered stacks gate. */
+export declare function ingressIssues({ doc, environment, spec, model }: {
+    doc: Parsed;
+    environment: Parsed;
+    spec?: Parsed;
+    model: Parsed;
+}): {
+    code: string;
+    at: any;
+    message: string;
+}[];
+/** HFS finder over the tracked rendered Swarm environments of either edition. */
+export declare function stacksIngressFindings(context: Parsed): import("./rule-types.mjs").Finding[];

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

@@ -3,85 +3,83 @@
 import { isPlainObject as plain } from '../../../engine/plain-object.mjs';
 import { repositoryOf } from '../../lib/stack-services.mjs';
 import { stacksDeploymentFindings } from './stacks-runtime.mjs';
-
 const PINNED = /@sha256:[a-f0-9]{64}$/i;
 const SUPPORTED = new Set(['traefik', 'caddy', 'caddy-docker-proxy']);
-const mapping = value => plain(value) ? value : {};
-const present = value => typeof value === 'string' && Boolean(value.trim());
-const imageName = image => present(image) ? repositoryOf(image).toLowerCase() : '';
-const ingressImage = image => SUPPORTED.has(imageName(image));
-
+const mapping = (value) => plain(value) ? value : {};
+const present = (value) => typeof value === 'string' && Boolean(value.trim());
+const imageName = (image) => present(image) ? repositoryOf(image).toLowerCase() : '';
+const ingressImage = (image) => SUPPORTED.has(imageName(image));
 function ingressIds(components, bindings, services, chosen) {
-  const ids = new Set();
-  if (present(chosen)) ids.add(chosen);
-  for (const id of Object.keys(bindings)) {
-    const component = mapping(components[id]);
-    if (component.role === 'ingress' || ingressImage(component.image)) ids.add(id);
-  }
-  for (const [id, entry] of Object.entries(services)) {
-    const service = mapping(entry), component = mapping(components[id]);
-    if (component.role === 'ingress' || ingressImage(service.image)) ids.add(id);
-  }
-  return [...ids];
+    const ids = new Set();
+    if (present(chosen))
+        ids.add(chosen);
+    for (const id of Object.keys(bindings)) {
+        const component = mapping(components[id]);
+        if (component.role === 'ingress' || ingressImage(component.image))
+            ids.add(id);
+    }
+    for (const [id, entry] of Object.entries(services)) {
+        const service = mapping(entry), component = mapping(components[id]);
+        if (component.role === 'ingress' || ingressImage(service.image))
+            ids.add(id);
+    }
+    return [...ids];
 }
-
 /** The name of the shared external ingress stack the environment declares, or null. */
-export const externalIngressStack = spec => present(spec?.ingress?.external?.stack) ? spec.ingress.external.stack : null;
-
+export const externalIngressStack = (spec) => present(spec?.ingress?.external?.stack) ? spec.ingress.external.stack : null;
 function externalIssues({ spec, candidates, at }) {
-  const ingress = mapping(spec.ingress), errors = [];
-  if (externalIngressStack(spec) === null || present(ingress.component) || !Array.isArray(ingress.hosts) || ingress.hosts.length === 0)
-    errors.push({ code: 'STACKS_INGRESS_UNDECLARED', at,
-      message: 'an external ingress is declared as ingress.external.stack with ingress.hosts and without ingress.component' });
-  if (candidates.length > 0)
-    errors.push({ code: 'STACKS_SECOND_INGRESS', at,
-      message: 'a stack that declares an external shared ingress must not render an ingress of its own' });
-  return errors;
+    const ingress = mapping(spec.ingress), errors = [];
+    if (externalIngressStack(spec) === null || present(ingress.component) || !Array.isArray(ingress.hosts) || ingress.hosts.length === 0)
+        errors.push({ code: 'STACKS_INGRESS_UNDECLARED', at,
+            message: 'an external ingress is declared as ingress.external.stack with ingress.hosts and without ingress.component' });
+    if (candidates.length > 0)
+        errors.push({ code: 'STACKS_SECOND_INGRESS', at,
+            message: 'a stack that declares an external shared ingress must not render an ingress of its own' });
+    return errors;
 }
-
 function declarationIssues({ chosen, components, bindings, services, candidates, at }) {
-  const errors = [];
-  if (!present(chosen) || components[chosen]?.role !== 'ingress' || !Object.hasOwn(bindings, chosen) || !Object.hasOwn(services, chosen))
-    errors.push({ code: 'STACKS_INGRESS_UNDECLARED', at,
-      message: 'Swarm ingress must name one component with role ingress that is inventoried, bound and present in the rendered model' });
-  const undeclared = candidates.filter(id => id !== chosen);
-  if (undeclared.length)
-    errors.push({ code: 'STACKS_INGRESS_UNDECLARED', at,
-      message: 'every rendered ingress must be the environment\'s declared ingress component' });
-  if (candidates.length > 1)
-    errors.push({ code: 'STACKS_SECOND_INGRESS', at,
-      message: 'a Swarm environment must run exactly one ingress component; a second ingress is forbidden' });
-  return errors;
+    const errors = [];
+    if (!present(chosen) || components[chosen]?.role !== 'ingress' || !Object.hasOwn(bindings, chosen) || !Object.hasOwn(services, chosen))
+        errors.push({ code: 'STACKS_INGRESS_UNDECLARED', at,
+            message: 'Swarm ingress must name one component with role ingress that is inventoried, bound and present in the rendered model' });
+    const undeclared = candidates.filter((id) => id !== chosen);
+    if (undeclared.length)
+        errors.push({ code: 'STACKS_INGRESS_UNDECLARED', at,
+            message: 'every rendered ingress must be the environment\'s declared ingress component' });
+    if (candidates.length > 1)
+        errors.push({ code: 'STACKS_SECOND_INGRESS', at,
+            message: 'a Swarm environment must run exactly one ingress component; a second ingress is forbidden' });
+    return errors;
 }
-
 function ingressImageIssues(ids, components, services) {
-  const errors = [];
-  for (const id of ids) {
-    for (const [prefix, source] of [['components', components], ['services', services]]) {
-      if (!Object.hasOwn(source, id)) continue;
-      const image = source[id]?.image;
-      if (!SUPPORTED.has(imageName(image)) || !PINNED.test(String(image)))
-        errors.push({ code: 'STACKS_INGRESS_UNKNOWN', at: `${prefix}.${id}.image`,
-          message: 'the declared ingress must use Traefik or Caddy pinned by a sha256 digest' });
+    const errors = [];
+    for (const id of ids) {
+        for (const [prefix, source] of [['components', components], ['services', services]]) {
+            if (!Object.hasOwn(source, id))
+                continue;
+            const image = source[id]?.image;
+            if (!SUPPORTED.has(imageName(image)) || !PINNED.test(String(image)))
+                errors.push({ code: 'STACKS_INGRESS_UNKNOWN', at: `${prefix}.${id}.image`,
+                    message: 'the declared ingress must use Traefik or Caddy pinned by a sha256 digest' });
+        }
     }
-  }
-  return errors;
+    return errors;
 }
-
 /** Static ingress contract shared by HFS and the rendered stacks gate. */
 export function ingressIssues({ doc, environment, spec = doc?.environments?.[environment], model }) {
-  if (spec?.runtime !== 'docker-swarm') return [];
-  const components = mapping(doc?.components), bindings = mapping(spec.components), services = mapping(model?.services);
-  const chosen = spec.ingress?.component, candidates = ingressIds(components, bindings, services, chosen);
-  const at = `environments.${environment}.ingress`;
-  if (mapping(spec.ingress).external !== undefined) return externalIssues({ spec, candidates, at });
-  return [
-    ...declarationIssues({ chosen, components, bindings, services, candidates, at }),
-    ...ingressImageIssues(candidates, components, services),
-  ];
+    if (spec?.runtime !== 'docker-swarm')
+        return [];
+    const components = mapping(doc?.components), bindings = mapping(spec.components), services = mapping(model?.services);
+    const chosen = spec.ingress?.component, candidates = ingressIds(components, bindings, services, chosen);
+    const at = `environments.${environment}.ingress`;
+    if (mapping(spec.ingress).external !== undefined)
+        return externalIssues({ spec, candidates, at });
+    return [
+        ...declarationIssues({ chosen, components, bindings, services, candidates, at }),
+        ...ingressImageIssues(candidates, components, services),
+    ];
 }
-
 /** HFS finder over the tracked rendered Swarm environments of either edition. */
 export function stacksIngressFindings(context) {
-  return stacksDeploymentFindings(context, ingressIssues);
+    return stacksDeploymentFindings(context, ingressIssues);
 }

package/runtime/scripts/hfs/rules/stacks-lite-backing.d.mts

@@ -0,0 +1,17 @@
+import type { Parsed, Repo } from './rule-types.mjs';
+/** The lite backing contract; full keeps its existing backing choices. */
+export declare function liteBackingIssues({ doc, environment, spec, model, repo, repoRoot, edition }: {
+    doc: Parsed;
+    environment: Parsed;
+    spec?: Parsed;
+    model: Parsed;
+    repo: Repo;
+    repoRoot?: string;
+    edition?: string;
+}): {
+    code: string;
+    at: string;
+    message: string;
+}[];
+/** HFS finder over tracked rendered models; unavailable evidence is reported by R267. */
+export declare function stacksLiteBackingFindings(context: Parsed): import("./rule-types.mjs").Finding[];