@starci/hfs 5.0.4 → 5.0.6

package/runtime/scripts/hfs/app-wiring.mjs

@@ -8,7 +8,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
-import { runNode } from '../api/node/run-node.mjs';
+import { runNode, runHeavyNode } from '../api/node/run-node.mjs';
 import { fileURLToPath } from 'node:url';
 import { invocationDir } from '../lib/roots.mjs';
 import { isMain } from '../lib/is-main.mjs';
@@ -174,7 +174,7 @@ function wiringApps(repo, files, prefix) {
     });
     return [...new Set([...declared, ...observed])];
 }
-function appWiringFinding({ repoRoot, beRoot, prefix, app, files, fixtures, timeout, run }) {
+function* appWiringFinding({ repoRoot, beRoot, prefix, app, files, fixtures, timeout }) {
     const file = `${prefix}${modulePath(app)}`;
     if (!/^[a-z][a-z0-9-]*$/.test(app) || !fs.existsSync(path.join(repoRoot, file)) || (files && !files.includes(file))) {
         return refusal(file, 'app module is missing');
@@ -184,10 +184,9 @@ function appWiringFinding({ repoRoot, beRoot, prefix, app, files, fixtures, time
     const args = [WORKER, '--worker', JSON.stringify({ repoRoot: beRoot, app, fixture: fixtureExists ? fixture : null, timeout })];
     const budget = workerBudget(timeout);
     const options = { cwd: beRoot, encoding: 'utf8', env: {}, windowsHide: true, timeout: budget, maxBuffer: 1024 * 1024 };
-    const spawnWorker = () => (run ? run(process.execPath, args, options) : runNode(args, options));
-    let result = spawnWorker();
+    let result = yield { args, options };
     if (isTimeout(result))
-        result = spawnWorker();
+        result = yield { args, options };
     if (isTimeout(result))
         return timedOut(file, budget);
     let proof;
@@ -199,7 +198,7 @@ function appWiringFinding({ repoRoot, beRoot, prefix, app, files, fixtures, time
         return refusal(file, SAFE_REASONS.has(proof?.reason) ? proof?.reason : WORKER_FAILURE);
     return null;
 }
-export function appWiring({ repoRoot, repo = readJson(repoRoot, 'hfs.json'), files, fixtures = {}, timeout = DEFAULT_TIMEOUT, run }) {
+function* wiringProgram({ repoRoot, repo = readJson(repoRoot, 'hfs.json'), files, fixtures = {}, timeout = DEFAULT_TIMEOUT }) {
     if (repo?.edition !== 'lite' || repo?.profile === 'fe' || repo?.kind === 'fe')
         return { ok: true, status: 'skipped', findings: [], apps: [] };
     const appRoot = Boolean(repo.sides);
@@ -208,12 +207,33 @@ export function appWiring({ repoRoot, repo = readJson(repoRoot, 'hfs.json'), fil
     const apps = wiringApps(repo, files, prefix);
     const findings = [];
     for (const app of apps) {
-        const finding = appWiringFinding({ repoRoot, beRoot, prefix, app, files, fixtures, timeout, run });
+        const finding = yield* appWiringFinding({ repoRoot, beRoot, prefix, app, files, fixtures, timeout });
         if (finding)
             findings.push(finding);
     }
     return { ok: findings.length === 0, status: 'checked', apps, findings };
 }
+/** The synchronous finder and its existing worker doubles drive the same proof program as app check. */
+export function appWiring(input) {
+    const program = wiringProgram(input);
+    let step = program.next();
+    while (!step.done) {
+        const { args, options } = step.value;
+        step = program.next(input.run ? input.run(process.execPath, args, options) : runNode(args, options));
+    }
+    return step.value;
+}
+/** The cache's asynchronous execution seam admits each boot attempt, with the same validation, timeout retry and result judgement. */
+export async function appWiringAsync(input) {
+    const program = wiringProgram(input);
+    let step = program.next();
+    while (!step.done) {
+        const { args, options } = step.value;
+        const result = await runHeavyNode(input.execute, { kind: 'test', label: 'app check wiring boot proof', args, cwd: options.cwd, env: options.env, timeoutMs: options.timeout, maxBuffer: options.maxBuffer });
+        step = program.next(result);
+    }
+    return step.value;
+}
 export function appWiringMain(argv, { cwd = invocationDir(), stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text) } = {}) {
     let directory = cwd, json = false;
     for (let at = 0; at < argv.length; at += 1) {

package/runtime/scripts/hfs/architecture/contract-bounds.d.mts

@@ -0,0 +1,3 @@
+import type { TypeScriptApi } from './config.mjs';
+/** True only for an unambiguous named export proven through actual declarations to a generated contract declaration. */
+export declare function isBoundsExport(ts: TypeScriptApi, target: string, name: string, ownsGenerated: (file: string) => boolean, seen?: Set<string>): boolean;

package/runtime/scripts/hfs/architecture/contract-bounds.mjs

@@ -0,0 +1,72 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+/** The generated input-bounds owner is contract data, not an operation. */
+const BOUNDS_MODULE = /(?:^|\/)__generated__\/input-bounds\.ts$/;
+/** Directly exported declarations with the requested name; multiple declarations are ambiguous. */
+function declaredExports(ts, source, name) {
+    let count = 0;
+    for (const statement of source.statements) {
+        if (!ts.canHaveModifiers(statement) || !ts.getModifiers(statement)?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword))
+            continue;
+        if (ts.isVariableStatement(statement)) {
+            count += statement.declarationList.declarations.filter(declaration => ts.isIdentifier(declaration.name) && declaration.name.text === name).length;
+        }
+        else if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement) || ts.isInterfaceDeclaration(statement) ||
+            ts.isTypeAliasDeclaration(statement) || ts.isEnumDeclaration(statement)) && statement.name?.text === name)
+            count += 1;
+    }
+    return count;
+}
+/** The concrete file a relative module specifier resolves to, in the same order as the rule's owner resolver. */
+function readSource(ts, target) {
+    for (const file of [`${target}.ts`, `${target}/index.ts`, target]) {
+        let text;
+        try {
+            text = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+        if (source.parseDiagnostics.length)
+            return null;
+        return { file, source };
+    }
+    return null;
+}
+/** True only for an unambiguous named export proven through actual declarations to a generated contract declaration. */
+export function isBoundsExport(ts, target, name, ownsGenerated, seen = new Set()) {
+    const found = readSource(ts, target);
+    if (!found)
+        return false;
+    const { file, source } = found;
+    const key = `${file}#${name}`;
+    if (seen.has(key) || seen.size >= 32)
+        return false;
+    const direct = declaredExports(ts, source, name);
+    const matches = [];
+    let wildcard = false;
+    for (const statement of source.statements) {
+        if (!ts.isExportDeclaration(statement))
+            continue;
+        const module = statement.moduleSpecifier && ts.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier.text : null;
+        if (!statement.exportClause) {
+            wildcard = true;
+            continue;
+        }
+        if (!ts.isNamedExports(statement.exportClause))
+            continue;
+        for (const item of statement.exportClause.elements)
+            if (item.name.text === name) {
+                matches.push({ origin: (item.propertyName ?? item.name).text, module });
+            }
+    }
+    if (wildcard || direct + matches.length !== 1)
+        return false;
+    if (BOUNDS_MODULE.test(file.replaceAll('\\', '/')))
+        return ownsGenerated(file) && direct === 1 && matches.length === 0;
+    const match = matches[0];
+    if (direct || !match || !match.module?.startsWith('.'))
+        return false;
+    return isBoundsExport(ts, resolve(dirname(file), match.module), match.origin, ownsGenerated, new Set([...seen, key]));
+}

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

@@ -243,7 +243,7 @@ function runHfsMachine(config, context, paths, injectedTypeScript, base, fast, v
         return hfsChecks;
     const graph = buildHfsGraph(config, hfsContext);
     const input = { config, context: hfsContext, graph, base };
-    const runs = { tiers: () => checkTiers(graph), reachability: () => checkReachability(input), deadExports: () => checkDeadExports(input),
+    const runs = { tiers: () => checkTiers(graph, hfsContext.ts), reachability: () => checkReachability(input), deadExports: () => checkDeadExports(input),
         requiredFiles: () => checkRequiredFiles(input), clones: () => checkClones(input), symbols: () => checkSymbols(input), docLanguage: () => checkDocLanguage(input) };
     if (graph.profile === 'be')
         for (const [name, [check]] of Object.entries(BACKEND_MACHINE))

package/runtime/scripts/hfs/architecture/tiers.d.mts

@@ -1,3 +1,4 @@
+import type { TypeScriptApi } from './config.mjs';
 import type { ArchitectureViolation, HfsGraph } from './hfs-graph.mjs';
 /**
  * HFS checks 1 and 2 (knowledge/hfs/slots.yaml `tiers`):
@@ -14,7 +15,7 @@ import type { ArchitectureViolation, HfsGraph } from './hfs-graph.mjs';
  * Importing inside one owner is always allowed; the public-entry rule stays with owners.mjs (ARCH_OWNER_EXPORT_BYPASS).
  */
 export declare const TIER_RULE_IDS: string[];
-export declare function checkTiers(graph: HfsGraph): {
+export declare function checkTiers(graph: HfsGraph, ts: TypeScriptApi): {
     violations: ArchitectureViolation[];
     coverage: {
         tierDirection: number;

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

@@ -1,4 +1,6 @@
 import { byCodeUnit } from '../../lib/list.mjs';
+import { dirname, relative } from 'node:path';
+import { isBoundsExport } from './contract-bounds.mjs';
 import { registryListImport, registrySlot } from './entity-registry.mjs';
 /**
  * HFS checks 1 and 2 (knowledge/hfs/slots.yaml `tiers`):
@@ -139,14 +141,53 @@ function reportReasonedTierViolation(graph, edge, answer, tierRule, counts, viol
         message,
     });
 }
-function inspectTierEdge(graph, edge, tierRule, counts, violations, coverage) {
+/** A public API entry may expose generated contract data without exposing operations to a hook. */
+function contractMetadataEdge(graph, ts, edge, verdict) {
+    if (graph.profile !== 'fe' || verdict.reason !== 'tierDirection')
+        return false;
+    const from = graph.files.get(edge.from);
+    const to = graph.files.get(edge.to);
+    if (from?.tier !== 'hooks' || to?.tier !== 'transport' || to.slot !== 'fe.modules.api' || !to.owner || to.owner.slot !== 'fe.modules' || to.owner.bindings.capability !== 'api')
+        return false;
+    // The tier verdict precedes private-entry checks, so prove both app isolation and the owner entry here.
+    const fromApp = graph.resolver.classifyPath(edge.from).bindings?.app;
+    const toApp = graph.resolver.classifyPath(edge.to).bindings?.app;
+    if (!fromApp || fromApp !== toApp || edge.to !== `${to.owner.root}/index.ts`)
+        return false;
+    const declaration = edge.edge.declaration;
+    let names;
+    if (ts.isImportDeclaration(declaration)) {
+        const clause = declaration.importClause;
+        if (!clause || clause.name || !clause.namedBindings || !ts.isNamedImports(clause.namedBindings))
+            return false;
+        names = clause.namedBindings.elements.map(item => (item.propertyName ?? item.name).text);
+    }
+    else if (ts.isExportDeclaration(declaration)) {
+        if (!declaration.exportClause || !ts.isNamedExports(declaration.exportClause))
+            return false;
+        names = declaration.exportClause.elements.map(item => (item.propertyName ?? item.name).text);
+    }
+    else
+        return false;
+    const apiOwner = to.owner;
+    const dirnameOfEntry = dirname(to.abs);
+    const ownsGenerated = (file) => {
+        const rel = `${apiOwner.root}/${relative(dirnameOfEntry, file).replaceAll('\\', '/')}`;
+        const classified = graph.resolver.classifyPath(rel);
+        const owner = graph.resolver.ownerOf(rel);
+        return classified.status === 'owned' && classified.slot === 'fe.transport.generated' &&
+            owner?.slot === apiOwner.slot && owner.root === apiOwner.root;
+    };
+    return names.length > 0 && names.every(name => isBoundsExport(ts, to.abs, name, ownsGenerated));
+}
+function inspectTierEdge(graph, ts, edge, tierRule, counts, violations, coverage) {
     const verdict = graph.resolver.importAllowed(edge.from, edge.to);
     if (verdict.reason === 'unowned' || verdict.reason?.startsWith('slot')) {
         coverage.unclassifiedEdges += 1;
         return;
     }
     coverage.edgesChecked += 1;
-    if (verdict.reason === 'tierDirection' && registryListImport(graph.resolver, edge))
+    if (verdict.reason === 'tierDirection' && (registryListImport(graph.resolver, edge) || contractMetadataEdge(graph, ts, edge, verdict)))
         return;
     reportReasonedTierViolation(graph, edge, verdict, tierRule, counts, violations);
 }
@@ -197,14 +238,14 @@ function addOwnerCycleViolations(adjacency, witness, violations) {
     }
     return components.length;
 }
-export function checkTiers(graph) {
+export function checkTiers(graph, ts) {
     const { resolver, profile } = graph;
     const violations = [];
     const tierRule = profile === 'be' ? 'BE_TIER_DIRECTION' : 'FE_TIER_DIRECTION';
     const coverage = { edgesChecked: 0, unclassifiedEdges: 0 };
     const counts = { tierDirection: 0, layerOrder: 0, crossApp: 0 };
     for (const edge of graph.edges)
-        inspectTierEdge(graph, edge, tierRule, counts, violations, coverage);
+        inspectTierEdge(graph, ts, edge, tierRule, counts, violations, coverage);
     // Owner cycles: nodes are owner units, edges the imports between two distinct units.
     const { adjacency, witness } = ownerAdjacency(graph, resolver);
     const cycles = addOwnerCycleViolations(adjacency, witness, violations);

package/runtime/scripts/hfs/ci-declaration.d.mts

@@ -45,11 +45,57 @@ export interface ValidCiDeclaration extends CiDeclaration {
 }
 /** True when readCiDeclaration found no problem in `declaration`. */
 export declare const isValidCiDeclaration: (declaration: CiDeclaration) => declaration is ValidCiDeclaration;
+/** A private endpoint uses an explicitly linked secret copy; public endpoints use the existing CI variable selector. */
+export declare function serviceHostSecret(service: ParsedDoc): string | null;
+/** Public credential selectors that ordinary child processes have no authority to inherit. */
+export declare function serviceCredentialNames(doc: ParsedDoc): string[];
+/** A project service's retrievable credential, and the explicitly linked CI execution copy. No value is held here. */
+export interface ServiceBinding {
+    service: string;
+    credential: string;
+    name: string;
+    repository: string;
+    projectKey: string;
+    environment: string;
+    member: string;
+    key: string;
+    path: string;
+}
+export interface BindingProblem {
+    at: string;
+    message: string;
+}
+/** An application runtime declaration or deploy grant selects runtime authority regardless of its CI name. */
+export declare function runtimeGranted(doc: ParsedDoc, environment: string, member: string, key: string): boolean;
+/** Read an actual member path, retaining the legacy dotenv suffix without guessing a plaintext twin. */
+export declare function serviceMemberPath(value: unknown): {
+    environment: string;
+    member: string;
+    path: string;
+} | null;
+/** The selected project's public credential reference, independent of CI: used for a sealed private endpoint too. */
+export declare function projectServiceCredential(doc: ParsedDoc, serviceId: string, credentialId: string, repository: string): ServiceBinding | null;
+/**
+ * Positive tooling classification: the selected product project, one explicit CI link, its own declared environment and exact
+ * member/key. Names alone, a sealed key alone, or credentials of a host or another project confer no tooling authority.
+ */
+export declare function serviceBindings(doc: ParsedDoc, repository: string): {
+    bindings: ServiceBinding[];
+    problems: BindingProblem[];
+};
+/** A sealed row belongs to this exact positive binding; a same-named key elsewhere remains unrelated custody. */
+export declare function boundSealedKey(binding: ServiceBinding, sealed: {
+    env?: string;
+    member?: string;
+    key: string;
+    file?: string;
+}): boolean;
 /** Each CI name belongs to one class and scope; declarations contain names and public configuration only. */
 export declare function readCiDeclaration(doc: ParsedDoc): CiDeclaration;
 /** Missing quality blocks preserve the existing rendered defaults; disabled services remain explicitly disabled. */
-export declare function qualityServices(doc: ParsedDoc, { example }?: {
+export declare function qualityServices(doc: ParsedDoc, { example, repository }?: {
     example?: boolean;
+    repository?: string | undefined;
 }): ParsedDoc;
 /** Read only encrypted envelope key names, never decrypting or returning any sealed value. */
 export declare function sealedKeyNames(root: string, { fs }: {

package/runtime/scripts/hfs/ci-declaration.mjs

@@ -5,6 +5,114 @@ import { parseYaml } from '../../engine/yaml.mjs';
 /** True when readCiDeclaration found no problem in `declaration`. */
 export const isValidCiDeclaration = (declaration) => declaration.problems.length === 0;
 const nameOf = (item) => typeof item === 'string' ? item : item?.name;
+/** A private endpoint uses an explicitly linked secret copy; public endpoints use the existing CI variable selector. */
+export function serviceHostSecret(service) {
+    const name = service?.ci?.hostVar || 'SONAR_HOST_URL';
+    return service?.host?.fromCredential && list(service?.ci?.secrets).some((link) => link?.name === name && link?.credential === service.host.fromCredential) ? name : null;
+}
+/** Public credential selectors that ordinary child processes have no authority to inherit. */
+export function serviceCredentialNames(doc) {
+    return [...new Set(Object.values(doc?.services ?? {}).flatMap((service) => [service?.ci?.token,
+            ...(service?.host?.fromCredential ? [service?.ci?.hostVar] : []), ...list(service?.ci?.secrets).map((entry) => entry?.name),
+            ...list(service?.credentials).flatMap((credential) => [credential?.env, credential?.key])]).filter((name) => typeof name === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/u.test(name)))];
+}
+const OPERATOR_CREDENTIAL = /(?:^|-)(?:admin|operator|provision|provisioning|global)(?:-|$)/iu;
+/** An application runtime declaration or deploy grant selects runtime authority regardless of its CI name. */
+export function runtimeGranted(doc, environment, member, key) {
+    const spec = doc?.environments?.[environment];
+    if (list(spec?.secrets).some((entry) => (entry?.member ?? /^secrets\/([a-z0-9-]+)/u.exec(entry?.where ?? '')?.[1] ?? entry?.name) === member
+        && (entry.key === key || (entry.key === undefined && (entry.keys === undefined || list(entry.keys).includes(key))))))
+        return true;
+    return list(spec?.deploy?.secrets?.grants).some((grant) => typeof grant?.service === 'string'
+        && list(grant.from).some((source) => source?.member === member && (source.keys === undefined || list(source.keys).includes(key))));
+}
+/** Read an actual member path, retaining the legacy dotenv suffix without guessing a plaintext twin. */
+export function serviceMemberPath(value) {
+    if (typeof value !== 'string')
+        return null;
+    const match = /^\.starcistacks\/([a-z][a-z0-9-]*)\/secrets\/([a-z][a-z0-9-]*)\.enc(?:\.yaml)?$/u.exec(value);
+    return match ? { environment: match[1], member: match[2], path: value } : null;
+}
+/** The selected project's public credential reference, independent of CI: used for a sealed private endpoint too. */
+export function projectServiceCredential(doc, serviceId, credentialId, repository) {
+    const service = doc?.services?.[serviceId], projects = list(service?.projects);
+    const selected = projects.filter((project) => project?.repository === repository);
+    const credentials = list(service?.credentials).filter((item) => item?.id === credentialId);
+    const credential = credentials.length === 1 ? credentials[0] : null, member = serviceMemberPath(credential?.custody?.path);
+    if (selected.length !== 1 || typeof selected[0]?.key !== 'string' || !selected[0].key || credential?.project !== selected[0].key
+        || projects.filter((project) => project?.key === credential?.project).length !== 1
+        || !member || credential.custody.repository !== repository || !Object.hasOwn(doc?.environments ?? {}, member.environment)
+        || typeof credential.key !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(credential.key)
+        || OPERATOR_CREDENTIAL.test(credentialId)
+        || runtimeGranted(doc, member.environment, member.member, credential.key))
+        return null;
+    // A tooling member carries one authority: another project's or the operator's credential cannot share its envelope.
+    if (list(service.credentials).some((item) => item !== credential && item?.custody?.repository === repository
+        && item?.custody?.path === member.path && (item?.project !== credential.project || OPERATOR_CREDENTIAL.test(String(item?.id)))))
+        return null;
+    return { service: serviceId, credential: credentialId, name: '', repository, projectKey: selected[0].key,
+        environment: member.environment, member: member.member, key: credential.key, path: member.path };
+}
+/**
+ * Positive tooling classification: the selected product project, one explicit CI link, its own declared environment and exact
+ * member/key. Names alone, a sealed key alone, or credentials of a host or another project confer no tooling authority.
+ */
+export function serviceBindings(doc, repository) {
+    const bindings = [], problems = [];
+    const bad = (at, message) => { problems.push({ at, message }); };
+    for (const [id, service] of Object.entries(doc?.services ?? {})) {
+        const links = list(service?.ci?.secrets);
+        const at = `services.${id}`;
+        if (id === 'codecov' && service?.auth === 'oidc' && (service.ci?.token || links.length || list(service.credentials).length))
+            bad(at, 'OIDC Codecov declares no stored token, credential or CI secret copy');
+        if (id === 'sonar' && service?.mode && service.mode !== 'disabled' && service.ci?.wiring === 'required'
+            && (!links.length || typeof service.ci.token !== 'string'))
+            bad(at, 'required product Sonar declares its analysis credential and CI binding to a sonar.enc.yaml member');
+        if (service?.host?.fromCredential && service.ci?.wiring === 'required' && !serviceHostSecret(service))
+            bad(`${at}.host.fromCredential`, 'a required private endpoint has an explicit credential-to-CI secret copy selected by ci.hostVar');
+        if (!links.length)
+            continue;
+        if (service.ci.token && !links.some((link) => link?.name === service.ci.token)) {
+            bad(`${at}.ci.token`, 'ci.token must select an explicit credential copy');
+            continue;
+        }
+        for (const link of links) {
+            const where = `${at}.ci.secrets`;
+            if (service?.mode === 'disabled' || service?.auth !== 'token') {
+                bad(where, 'credential copies require an enabled token-authenticated service');
+                continue;
+            }
+            const references = list(service.credentials).filter((credential) => credential?.id === link?.credential);
+            const other = references.length === 1 && list(service.projects).find((project) => project?.key === references[0]?.project);
+            if (other && other.repository !== repository)
+                continue;
+            const binding = typeof link?.credential === 'string' ? projectServiceCredential(doc, id, link.credential, repository) : null;
+            if (!binding || typeof link?.name !== 'string' || !/^[A-Z][A-Z0-9_]*$/u.test(link.name)
+                || links.filter((item) => item?.name === link.name).length !== 1) {
+                bad(where, 'each unique CI copy selects one project credential in its own declared environment/member/key, separate from operator and app runtime authority');
+                continue;
+            }
+            if (id === 'sonar' && link.name === service.ci.token && binding.path !== `.starcistacks/${binding.environment}/secrets/sonar.enc.yaml`) {
+                bad(where, 'Sonar analysis custody is the product environment\'s sonar.enc.yaml member');
+                continue;
+            }
+            bindings.push({ ...binding, name: link.name });
+        }
+    }
+    for (const binding of [...bindings]) {
+        if (bindings.filter((item) => item.name === binding.name).length > 1)
+            bad('services', `CI secret ${binding.name} has ambiguous service custody`);
+    }
+    const sonar = doc?.services?.sonar;
+    if (sonar?.mode && sonar.mode !== 'disabled' && sonar.ci?.wiring === 'required'
+        && !bindings.some((binding) => binding.service === 'sonar' && binding.name === sonar.ci.token))
+        bad('services.sonar', 'required Sonar analysis has no credential binding for the selected product project');
+    return { bindings: bindings.filter((binding) => bindings.filter((item) => item.name === binding.name).length === 1), problems };
+}
+/** A sealed row belongs to this exact positive binding; a same-named key elsewhere remains unrelated custody. */
+export function boundSealedKey(binding, sealed) {
+    return binding.environment === sealed.env && binding.member === sealed.member && binding.key === sealed.key && binding.path === sealed.file;
+}
 /** A public CI variable declares either a manifest value or an owner-supplied value, never both. */
 function variableProblems(item, at, invalid) {
     const hasValue = item != null && Object.hasOwn(item, 'value');
@@ -44,14 +152,18 @@ export function readCiDeclaration(doc) {
     return { secrets, vars, dependabotSecrets, problems };
 }
 /** Missing quality blocks preserve the existing rendered defaults; disabled services remain explicitly disabled. */
-export function qualityServices(doc, { example = false } = {}) {
+export function qualityServices(doc, { example = false, repository } = {}) {
     const services = doc?.services ?? {}, sonar = services.sonar, codecov = services.codecov ?? {};
     const dependabot = services.dependabot ?? {}, audit = services.audit ?? {};
     return {
         sonar: !sonar || sonar.mode === 'disabled' ? null : {
             provider: sonar.provider, mode: sonar.mode, host: sonar.host?.public || sonar.host?.local || null,
+            hostCredential: sonar.host?.fromCredential ?? null,
+            hostSecret: serviceHostSecret(sonar),
             organization: sonar.organization ?? null,
-            organizationVar: sonar.ci?.organizationVar ?? (sonar.provider === 'sonarcloud' && (example || list(sonar.runtimeSecrets).length > 0) && !list(sonar.credentials).length ? 'SONAR_ORGANIZATION' : null), projectKey: sonar.projects?.[0]?.key ?? null,
+            organizationVar: sonar.ci?.organizationVar ?? (sonar.provider === 'sonarcloud' && (example || list(sonar.runtimeSecrets).length > 0) && !list(sonar.credentials).length ? 'SONAR_ORGANIZATION' : null),
+            projectKey: (repository ? list(sonar.projects).find((project) => project?.repository === repository) : sonar.projects?.[0])?.key ?? null,
+            credentials: sonar.credentials ?? [], projects: sonar.projects ?? [], auth: sonar.auth, ci: sonar.ci ?? {},
             qualityGate: sonar.qualityGate ?? (example ? 'starci-quality-lite' : 'starci-quality'), wiring: sonar.ci?.wiring ?? 'required',
             token: sonar.ci?.token || nameOf(sonar.ci?.secrets?.[0]) || 'SONAR_TOKEN', hostVar: sonar.ci?.hostVar || 'SONAR_HOST_URL',
         },
@@ -115,7 +227,7 @@ export function ciNamesOfServices(doc) {
         if (ci.token)
             out.push({ service, name: ci.token, kind: 'secret' });
         if (ci.hostVar)
-            out.push({ service, name: ci.hostVar, kind: 'var' });
+            out.push({ service, name: ci.hostVar, kind: entry?.host?.fromCredential ? 'secret' : 'var' });
         if (ci.organizationVar)
             out.push({ service, name: ci.organizationVar, kind: 'var' });
         for (const item of list(ci.secrets))

package/runtime/scripts/hfs/repo-identity.d.mts

@@ -1,3 +1,5 @@
+/** Identity queries need repository configuration, never age identities or selected service connection credentials. */
+export declare function identityQueryEnvironment(parent: NodeJS.ProcessEnv, privateNames?: readonly string[]): NodeJS.ProcessEnv;
 /** What git says about a folder. */
 export interface RepoIdentity {
     inWorkTree: boolean;
@@ -10,6 +12,8 @@ export interface RepoIdentity {
  * name outside Git, else the folder name. A folder inside a larger repository (a nested product, an example) is named by
  * its own folder.
  */
-export declare function repositoryName(root: string): string;
+export declare function repositoryName(root: string, { env }?: {
+    env?: NodeJS.ProcessEnv;
+}): string;
 /** The folder whose siblings are this repository's sibling repositories: the main checkout for a worktree, else root. */
 export declare function repositoryHome(root: string): string;

package/runtime/scripts/hfs/repo-identity.mjs

@@ -5,10 +5,15 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { revParseQuery } from '../api/git/rev-parse-query.mjs';
 import { remote as gitRemote } from '../api/git/remote.mjs';
-import { gitOutputOf } from '../lib/git.mjs';
+import { gitOutputOf, withoutGitLocalEnv } from '../lib/git.mjs';
 import { trimTrailingSlashes } from './trailing-slashes.mjs';
 /** One git call (a scripts/api/git call file) in `root`: its trimmed stdout; throws unless git exits 0. */
-const git = (call, root, args) => gitOutputOf(call(args, { cwd: root })).trim(); // gitOutputOf threw unless git exited 0, whose stdout is text
+const git = (call, root, args, env) => gitOutputOf(call(args, { cwd: root, env: identityQueryEnvironment(env) })).trim(); // gitOutputOf threw unless git exited 0, whose stdout is text
+/** Identity queries need repository configuration, never age identities or selected service connection credentials. */
+export function identityQueryEnvironment(parent, privateNames = []) {
+    const selected = new Set(privateNames.map((name) => name.toUpperCase()));
+    return Object.fromEntries(Object.entries(withoutGitLocalEnv(parent)).filter(([name]) => !selected.has(name.toUpperCase()) && !/^(?:SOPS_AGE_KEY(?:_FILE)?|SONAR_.*)$/iu.test(name)));
+}
 const real = (p) => { try {
     return fs.realpathSync(p);
 }
@@ -26,20 +31,20 @@ catch {
     return null;
 } };
 /** { repositoryRoot, inWorkTree, home } for `root`: home is the main checkout folder when root is a repository top level. */
-function identityOf(root) {
+function identityOf(root, env = process.env) {
     const state = stateOf(root);
     if (state === null)
-        return askGit(root);
+        return askGit(root, env);
     if (!known.has(state))
-        known.set(state, askGit(root));
+        known.set(state, askGit(root, env));
     return known.get(state);
 }
-function askGit(root) {
+function askGit(root, env) {
     let inWorkTree = false, repositoryRoot = false, home = null;
     try {
         // Identity comes from Git only when root IS a repository (or worktree) top level, never a folder inside one.
         // One git call answers both questions: the top level on the first line, the common git dir on the second.
-        const [top, commonDir] = git(revParseQuery, root, ['--show-toplevel', '--git-common-dir']).split(String.fromCodePoint(10)).map((line) => line.trim());
+        const [top, commonDir] = git(revParseQuery, root, ['--show-toplevel', '--git-common-dir'], env).split(String.fromCodePoint(10)).map((line) => line.trim());
         repositoryRoot = real(top) === real(root);
         inWorkTree = true;
         const common = path.resolve(root, commonDir);
@@ -55,11 +60,11 @@ function askGit(root) {
  * name outside Git, else the folder name. A folder inside a larger repository (a nested product, an example) is named by
  * its own folder.
  */
-export function repositoryName(root) {
-    const { inWorkTree, repositoryRoot, home } = identityOf(root);
+export function repositoryName(root, { env = process.env } = {}) {
+    const { inWorkTree, repositoryRoot, home } = identityOf(root, env);
     if (repositoryRoot) {
         try {
-            const remote = trimTrailingSlashes(git(gitRemote, root, ['get-url', 'origin'])).replace(GIT_SUFFIX, '');
+            const remote = trimTrailingSlashes(git(gitRemote, root, ['get-url', 'origin'], env)).replace(GIT_SUFFIX, '');
             const name = remote.split(/[/:]/u).pop();
             if (name)
                 return name;

package/runtime/scripts/hfs/rules/ci-custody.mjs

@@ -2,7 +2,8 @@
 import fs from 'node:fs';
 import { list } from '../../lib/list.mjs';
 import { findStackDeclaration, STACK_ROOT } from '../../lib/stack-declaration.mjs';
-import { readCiDeclaration, sealedKeyNames, workflowReferences, ciNamesOfServices } from '../ci-declaration.mjs';
+import { readCiDeclaration, sealedKeyNames, workflowReferences, ciNamesOfServices, serviceBindings, boundSealedKey, runtimeGranted, serviceCredentialNames } from '../ci-declaration.mjs';
+import { repositoryName, identityQueryEnvironment } from '../repo-identity.mjs';
 import { found } from './read.mjs';
 const DECLARATION = `${STACK_ROOT}/application-stacks.yaml`;
 const named = (entry) => typeof entry.name === 'string' && /^[A-Z][A-Z0-9_]*$/.test(entry.name);
@@ -10,38 +11,18 @@ const identity = (kind, name) => `${kind}:${name}`;
 const atCi = (section) => `${DECLARATION}#ci.${section}`;
 /** The variables the managed workflows themselves read; an app declares none of them. STARCI_DEPLOY_PAUSED is the brake of the automatic deploy, set per GitHub environment by the owner. */
 const MANAGED_VARIABLES = ['STARCI_DEPLOY_PAUSED'];
-/** A CI or Dependabot secret must never also live in a sealed app member. */
-function sealedFindings(ci, sealed) {
+/** A sealed CI copy has exact service/project custody; every other sealed CI key remains refused. */
+function sealedFindings(ci, sealed, bindings) {
     const names = new Set([...ci.secrets, ...ci.dependabotSecrets].filter(named).map((entry) => entry.name));
-    return sealed.filter(({ key }) => names.has(key)).map(({ key, file }) => found('CI_SECRET_SEALED', file, `${key} is a CI secret (GitHub reads it) but it is sealed in ${file} for app containers; one key, one class: remove it from the member (starci app secret unset --env <env> ...) and set it with starci app ci secret set ${key} --execute`));
+    const copies = bindings.filter((binding) => names.has(binding.name));
+    return sealed.filter((entry) => (names.has(entry.key) || copies.some((binding) => binding.key === entry.key))
+        && !copies.some((binding) => boundSealedKey(binding, entry))).map(({ key, file }) => found('CI_SECRET_SEALED', file, `${key} is a CI secret sealed in ${file} without an exact project service binding; app runtime keys stay in their members and tooling copies name services.<id>.ci.secrets[].credential`));
 }
-/** A source selects sealed keys only from its own member and environment. */
-function sourceRuntimeFindings(source, grant, environment, { sealed, names, findings, seen }) {
-    for (const entry of sealed) {
-        if (entry.env !== environment || entry.member !== source?.member || !names.has(entry.key))
-            continue;
-        if (source.keys !== undefined && !list(source.keys).includes(entry.key))
-            continue;
-        const id = `${entry.file}:${grant.service}:${entry.key}`;
-        if (seen.has(id))
-            continue;
-        seen.add(id);
-        findings.push(found('APP_SECRET_IN_CI', entry.file, `${entry.key} is read by the ${grant.service} container at runtime through the ${environment} deploy grant; keep it in the .enc and drop it from ci`));
-    }
-}
-/** Only keys actually selected by a grant, in that grant's environment and member, are runtime consumers. */
+/** Runtime declarations and grants select exact environment/member/key consumers; an unselected key is unrelated. */
 function runtimeFindings(doc, ci, sealed) {
     const names = new Set([...ci.secrets, ...ci.vars].filter(named).map((entry) => entry.name));
-    const findings = [], seen = new Set();
-    for (const [environment, spec] of Object.entries(doc.environments ?? {})) {
-        for (const grant of list(spec?.deploy?.secrets?.grants)) {
-            if (typeof grant?.service !== 'string')
-                continue;
-            for (const source of list(grant.from))
-                sourceRuntimeFindings(source, grant, environment, { sealed, names, findings, seen });
-        }
-    }
-    return findings;
+    return sealed.filter((entry) => names.has(entry.key) && runtimeGranted(doc, entry.env, entry.member, entry.key))
+        .map((entry) => found('APP_SECRET_IN_CI', entry.file, `${entry.key} is selected by an app runtime declaration or deploy grant in ${entry.env}; keep it sealed and drop it from ci`));
 }
 /** Workflow reads are class-sensitive; legacy lists remain readable, but an absent ci block always signals migration once per name. */
 function workflowFindings(doc, declared, references) {
@@ -50,7 +31,7 @@ function workflowFindings(doc, declared, references) {
     if (hasCi) {
         for (const entry of ciNamesOfServices(doc).filter(named)) {
             const legacy = list(doc.services?.[entry.service]?.ci?.[`${entry.kind}s`]);
-            if (legacy.some((item) => (typeof item === 'string' ? item : item?.name) === entry.name))
+            if (legacy.some((item) => (typeof item === 'string' ? item : !item?.credential ? item?.name : null) === entry.name))
                 allowed.add(identity(`${entry.kind}s`, entry.name));
         }
     }
@@ -82,7 +63,11 @@ function driftFindings(doc, ci, references) {
     }
     const names = new Set(declared.map(({ kind, name }) => identity(kind, name)));
     for (const [service, entry] of Object.entries(doc.services ?? {})) {
-        for (const [field, kind] of [['token', 'secrets'], ['hostVar', 'vars']]) {
+        for (const binding of list(entry?.ci?.secrets)) {
+            if (typeof binding?.credential === 'string' && !names.has(identity('secrets', binding.name)))
+                findings.push(found('CI_DECLARATION_DRIFT', atCi('secrets'), `services.${service}.ci.secrets names ${binding.name}, which is not declared in ci.secrets`));
+        }
+        for (const [field, kind] of [['token', 'secrets'], ['hostVar', entry?.host?.fromCredential ? 'secrets' : 'vars']]) {
             const name = entry?.ci?.[field];
             if (typeof name !== 'string' || names.has(identity(kind, name)))
                 continue;
@@ -99,7 +84,11 @@ export function ciCustodyFindings({ repoRoot, repo, isRoot }) {
     if (!doc)
         return [];
     const ci = readCiDeclaration(doc);
+    const selected = serviceBindings(doc, repositoryName(repoRoot, { env: identityQueryEnvironment(process.env, serviceCredentialNames(doc)) }));
     const sealed = sealedKeyNames(repoRoot, { fs });
     const references = workflowReferences(repoRoot, { fs });
-    return [...sealedFindings(ci, sealed), ...runtimeFindings(doc, ci, sealed), ...driftFindings(doc, ci, references)];
+    const missing = selected.bindings.filter((binding) => !sealed.some((entry) => boundSealedKey(binding, entry)))
+        .map((binding) => found('CI_SECRET_SEALED', binding.path, 'the selected service credential member/key is not sealed in this product custody'));
+    return [...selected.problems.map((problem) => found('CI_SECRET_SEALED', `${DECLARATION}#${problem.at}`, problem.message)), ...missing,
+        ...sealedFindings(ci, sealed, selected.bindings), ...runtimeFindings(doc, ci, sealed), ...driftFindings(doc, ci, references)];
 }