@starci/hfs 5.0.5 → 5.0.7

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)];
 }

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

@@ -22,7 +22,9 @@ import { fileURLToPath } from 'node:url';
 import { loadTypescript } from '../../lib/package-at.mjs';
 import { parseYaml } from '../../../engine/yaml.mjs';
 import { envelopeOf } from '../secret-document.mjs';
-import { SSH_GROUP, sshTransportMembers } from '../secret-standard.mjs';
+import { SSH_GROUP, sshTransportMembers, declaredServiceKeys } from '../secret-standard.mjs';
+import { repositoryName, identityQueryEnvironment } from '../repo-identity.mjs';
+import { serviceCredentialNames } from '../ci-declaration.mjs';
 import { memberOfName } from '../../lib/sealed-member.mjs';
 import { found, readText } from './read.mjs';
 export const ENV_REQUIRED_UNSET = 'ENV_REQUIRED_UNSET';
@@ -342,12 +344,12 @@ function addRequiredFindings(reads, sealed, declared, findings) {
         }
     }
 }
-function sealedMemberFinding(key, member, reads, declared) {
+function sealedMemberFinding(key, member, reads, declared, serviceConsumer) {
     // The specific public-custody code wins over the generic unread one for a NEXT_PUBLIC_* key.
     if (key.startsWith('NEXT_PUBLIC_')) {
         return found(ENV_PUBLIC_SEALED, member, `${member} seals the public key ${key}; NEXT_PUBLIC_* values are public configuration and never enter custody`);
     }
-    if (!reads.has(key) && !declared.has(key)) {
+    if (!reads.has(key) && !declared.has(key) && !serviceConsumer(member, key)) {
         return found(ENV_SEALED_UNREAD, member, `${member} seals ${key}, which no EnvSource reader and no declared consumer uses; unseal it or declare who consumes it`);
     }
     return null;
@@ -362,10 +364,10 @@ function transportMembers(repoRoot) {
     catch { /* a malformed stacks yaml is the shape rule's finding, not this one's */ }
     return (environment) => sshTransportMembers(stacks.environments?.[environment]);
 }
-function addSealedFindings(sealed, reads, declared, transport, findings) {
+function addSealedFindings(sealed, reads, declared, transport, findings, serviceConsumer) {
     for (const [key, members] of sealed) {
         for (const member of members) {
-            const finding = sealedMemberFinding(key, member, reads, declared);
+            const finding = sealedMemberFinding(key, member, reads, declared, serviceConsumer);
             if (finding !== null)
                 findings.push(finding);
         }
@@ -410,8 +412,15 @@ export function envParityFindings({ repoRoot, all = [], isRoot }) {
     const sealed = sealedKeys(repoRoot, all);
     const declared = declaredKeys(repoRoot, all);
     const findings = [];
+    let stacks = {};
+    try {
+        stacks = parseYaml(readText(repoRoot, '.starcistacks/application-stacks.yaml') ?? '') ?? {};
+    }
+    catch { /* the shape owner reports invalid YAML */ }
+    const repository = repositoryName(repoRoot, { env: identityQueryEnvironment(process.env, serviceCredentialNames(stacks)) });
+    const serviceConsumer = (file, key) => declaredServiceKeys(stacks, repository, file.split('/')[1], memberOfName(file.split('/').pop())).includes(key);
     addRequiredFindings(reads, sealed, declared, findings);
-    addSealedFindings(sealed, reads, declared, transportMembers(repoRoot), findings);
+    addSealedFindings(sealed, reads, declared, transportMembers(repoRoot), findings, serviceConsumer);
     addExampleFindings(repoRoot, all, reads, findings);
     return findings;
 }

package/runtime/scripts/hfs/secret-standard.d.mts

@@ -46,6 +46,7 @@ export interface MoveOptions {
 }
 /** The provider a key belongs to: its first word (`SEPAY_IPN_SECRET_KEY` is `sepay`, `OPENROUTER_API_KEY` is `openrouter`). */
 export declare const providerOf: (key: string) => string;
+export declare function declaredServiceKeys(document: StacksDocument, repository: string, environment: string, member: string): string[];
 /** The keys of the one sealed SSH member `deploy.remote.sealed` names (stack/remote.mjs): the deploy transport reads exactly these. */
 export declare const SSH_GROUP: readonly string[];
 /**

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

@@ -13,12 +13,26 @@ import { configuredRecipients } from "./secret-init.mjs";
 import { envelopeOf, validateMap } from "./secret-document.mjs";
 import { deleteSealed, fileOf, sealedFiles, writeSecret } from "./secret-store.mjs";
 import { SecretError } from "./secret-errors.mjs";
+import { serviceMemberPath, serviceCredentialNames } from "./ci-declaration.mjs";
+import { repositoryName, identityQueryEnvironment } from "./repo-identity.mjs";
+import { list } from "../lib/list.mjs";
 /** The provider a key belongs to: its first word (`SEPAY_IPN_SECRET_KEY` is `sepay`, `OPENROUTER_API_KEY` is `openrouter`). */
 export const providerOf = (key) => key.split("_")[0].toLowerCase();
 const sameSet = (left, right) => left.length === right.length && left.every((item) => right.includes(item));
 const keyList = (keys) => keys.join(", ");
 /** The member a `secrets:` entry names: `member`, else the slug of `where`, else its `name`. */
 const memberOfEntry = (entry) => entry?.member ?? /^secrets\/([a-z0-9-]+)/u.exec(entry?.where ?? "")?.[1] ?? entry?.name;
+/** The declared connection/credential keys of this project's services, including separately kept operator login custody. */
+function declaredServiceReferences(document, repository) {
+    const services = document.services;
+    return Object.values(services ?? {}).flatMap((service) => list(service?.credentials).flatMap((credential) => {
+        const selected = serviceMemberPath(credential?.custody?.path);
+        return credential?.custody?.repository === repository && selected && typeof credential.key === "string" ? [{ ...selected, key: credential.key }] : [];
+    }));
+}
+export function declaredServiceKeys(document, repository, environment, member) {
+    return declaredServiceReferences(document, repository).filter((reference) => reference.environment === environment && reference.member === member).map((reference) => reference.key);
+}
 /** The keys an environment's `secrets:` declares for `member`: an entry naming `key` with that `member`, or a whole-member entry. */
 function declaredKeys(spec, member, keys) {
     const entries = Array.isArray(spec?.secrets) ? spec.secrets : [];
@@ -80,6 +94,11 @@ export function auditSecrets(repoRoot, environment = null) {
             .map((entry) => entry.name)
             .sort();
     const findings = [];
+    const repository = repositoryName(repoRoot, { env: identityQueryEnvironment(process.env, serviceCredentialNames(stacks)) });
+    for (const reference of declaredServiceReferences(stacks, repository).filter((item) => !environment || item.environment === environment)) {
+        if (!Object.hasOwn(stacks.environments ?? {}, reference.environment) || !fs.existsSync(path.join(repoRoot, reference.path)))
+            findings.push({ code: "MISSING", env: reference.environment, member: reference.member, detail: "service credential references a missing member or undeclared environment" });
+    }
     for (const env of environments) {
         const directory = path.join(root, env, "secrets");
         const spec = stacks.environments?.[env];
@@ -92,16 +111,17 @@ export function auditSecrets(repoRoot, environment = null) {
             const providers = [...new Set(envelope.keys.map(providerOf))];
             if (isLegacyName(name))
                 add("LEGACY_MEMBER", `is a dotenv .enc member; move it: starci app secret migrate --env ${env} ${member} [--to <provider>] --execute`);
-            if (providers.length > 1 && !declaredGroup(spec, member, envelope.keys))
+            const serviceKeys = declaredServiceKeys(stacks, repository, env, member);
+            if (providers.length > 1 && !declaredGroup(spec, member, envelope.keys) && !envelope.keys.every((key) => serviceKeys.includes(key)))
                 add("MIXED_PROVIDERS", `holds keys of ${providers.length} providers by their first word (${providers.join(", ")}) that the stack does not group in it; split it (starci app secret split --env ${env} ${member} [--group KEY=member] --execute) or declare its keys in environments.${env}.secrets (an entry naming ${member} with keys: [...])`);
             const wanted = recipientsFor(repoRoot, path.join(directory, `${member}${MEMBER_SUFFIX}`));
             if (!isLegacyName(name) && wanted.length && !sameSet(wanted, envelope.recipients))
                 add("RECIPIENT_DRIFT", `is sealed to ${keyList(envelope.recipients)}, its environment's rule names ${keyList(wanted)}; seal it again: starci app secret migrate --env ${env} ${member} --execute`);
             if (spec) {
-                const declared = declaredKeys(spec, member, envelope.keys);
+                const declared = [...declaredKeys(spec, member, envelope.keys), ...serviceKeys];
                 const missing = envelope.keys.filter((key) => !declared.includes(key));
                 if (missing.length)
-                    add("UNDECLARED_KEY", `holds ${keyList(missing)}, not declared in environments.${env}.secrets of application-stacks.yaml`);
+                    add("UNDECLARED_KEY", `holds ${keyList(missing)}, not declared as runtime secrets or exact service credential references in application-stacks.yaml`);
             }
             if (tracked && !tracked.has(name))
                 add("UNTRACKED", "is not committed; commit it (it is ciphertext)");
@@ -155,7 +175,8 @@ export function declareKeys(repoRoot, environment, member, keys) {
     const spec = document.environments?.[environment];
     if (!spec)
         return { declared: [], byHand: [] };
-    const missing = keys.filter((key) => !declaredKeys(spec, member, keys).includes(key));
+    const serviceKeys = declaredServiceKeys(document, repositoryName(repoRoot, { env: identityQueryEnvironment(process.env, serviceCredentialNames(document)) }), environment, member);
+    const missing = keys.filter((key) => !declaredKeys(spec, member, keys).includes(key) && !serviceKeys.includes(key));
     if (!missing.length)
         return { declared: [], byHand: [] };
     // A swarm environment's secret is a versioned external secret its stack file names (runtimeName, deploy grants): its

package/runtime/scripts/hfs/secret-store.d.mts

@@ -1,7 +1,12 @@
 import { type SecretSops } from "./secret-sops.mjs";
+import type { ServiceBinding } from "./ci-declaration.mjs";
 /** The directory of the sealed secrets of the app at `repoRoot` for `env`; the one env that has secrets when none is named. */
 export declare function secretsDirectory(repoRoot: string, env?: string | null): string;
 export declare const fileOf: (directory: string, slug: string | undefined) => string;
+/** Judge a selected service member and cleartext key names without decrypting; its real path stays in this product. */
+export declare function serviceCredentialFile(repoRoot: string, binding: ServiceBinding): string;
+/** Native service loader: one exact key, decrypted in memory through the common identity/SOPS owner, never an env fallback. */
+export declare function serviceCredentialValue(repoRoot: string, binding: ServiceBinding, sops: Pick<SecretSops, "decrypt">): string;
 /** Replace one existing sealed member with an already validated envelope: same claim and atomic publish as set. */
 export declare const replaceSealed: (file: string, sealed: string) => void;
 /** Delete one sealed member under the writer claim. */

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

@@ -41,6 +41,37 @@ export const fileOf = (directory, slug) => {
         throw new SecretError(error.message);
     }
 };
+/** Judge a selected service member and cleartext key names without decrypting; its real path stays in this product. */
+export function serviceCredentialFile(repoRoot, binding) {
+    const file = fileOf(secretsDirectory(repoRoot, binding.environment), binding.member);
+    const declared = path.resolve(repoRoot, binding.path);
+    try {
+        if (file !== declared || !fs.statSync(file).isFile() || fs.realpathSync(file) !== path.join(fs.realpathSync(repoRoot), binding.path))
+            throw new SecretError("service custody must name one regular sealed member inside this product");
+        if (!envelopeOf(fs.readFileSync(file, "utf8")).keys.includes(binding.key))
+            throw new SecretError("service custody does not hold the declared key");
+    }
+    catch {
+        throw new SecretError("service custody is missing, ambiguous or outside this product");
+    }
+    return file;
+}
+/** Native service loader: one exact key, decrypted in memory through the common identity/SOPS owner, never an env fallback. */
+export function serviceCredentialValue(repoRoot, binding, sops) {
+    const file = serviceCredentialFile(repoRoot, binding);
+    try {
+        const envelope = envelopeOf(fs.readFileSync(file, "utf8"));
+        if (!envelope.keys.includes(binding.key))
+            throw new SecretError("service credential key is absent from the selected member");
+        const value = sops.decrypt(file, envelope.format)[binding.key];
+        if (typeof value !== "string" || !value.length)
+            throw new SecretError("service credential key is empty or absent");
+        return value;
+    }
+    catch {
+        throw new SecretError("service credential custody could not be opened; check its member, key and owner identity");
+    }
+}
 /**
  * Build and validate a replacement envelope without publishing it. An existing member is decrypted only when it holds a key
  * `values` does not replace; a member whose every key is replaced (the one-key member a `set` re-seals) needs no age identity.

package/src/main.mjs

@@ -64,7 +64,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 //   starci app secret materialize --env <env> | list --env <env> | verify --env <env> | recipients --env <env> [--add|--remove <age1...|owner>] [--execute]
 //                                            dotenv custody in .starcistacks, public age rule initialization, private KEY files outside Git;
 //                                            values reach stdout only when get explicitly receives --reveal.
-//   starci app ci secret set <NAME> [--env E | --dependabot] [--repo owner/name] [--execute]  reads the value from stdin only; dry until --execute.
+//   starci app ci secret set <NAME> [--from-custody] [--env E | --dependabot] [--repo owner/name] [--execute]  stdin or the explicit service custody binding; dry until --execute.
 //   starci app ci var set <NAME> [--env E] [--value v] [--execute] | var sync [--execute] | verify [--json] | local [--execute]
 //                                            declared GitHub CI custody; verify compares names, scopes and public values; local prints the CI plan, --execute runs it.
 //   starci app db new <name> | baseline | restamp --map <restamp.yaml> | migrate | post-cutover | dump | drift   [--db-url-env <NAME>]

package/sync/ci-commands.mjs

@@ -35,7 +35,7 @@ function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
     if (!sonar)
         return '';
     const condition = SONAR_CONDITION;
-    const host = sonar.provider === 'sonarcloud' ? 'https://sonarcloud.io' : `\${{ vars.${sonar.hostVar} }}`;
+    const host = sonar.hostSecret ? `\${{ secrets.${sonar.hostSecret} }}` : sonar.provider === 'sonarcloud' ? 'https://sonarcloud.io' : `\${{ vars.${sonar.hostVar} }}`;
     const header = [
         '  sonar:',
         '    needs: [plan, lint, coverage]',
@@ -52,6 +52,7 @@ function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
         `        if: ${condition}`,
         '        run: |',
         `          if [ -z "$SONAR_TOKEN" ]; then echo "::error::SONAR_TOKEN is not set: Sonar is required, so a missing token fails this job (secret ${sonar.token})"; exit 1; fi`,
+        '          if [ -z "$SONAR_HOST_URL" ]; then echo "::error::SONAR_HOST_URL is not set: the declared analysis endpoint is required"; exit 1; fi',
         `      - uses: ${DOWNLOAD_ARTIFACT}`,
         `        if: ${condition}`,
         '        with:',

package/sync/quality-services.mjs

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
-import { qualityServices } from '../runtime/scripts/hfs/ci-declaration.mjs';
+import { qualityServices, serviceCredentialNames } from '../runtime/scripts/hfs/ci-declaration.mjs';
+import { repositoryName, identityQueryEnvironment } from '../runtime/scripts/hfs/repo-identity.mjs';
 import { isRuntimeExampleApp } from '../runtime/scripts/lib/runtime-example.mjs';
 import { badgeTokenNotices, renderReadmeBadges } from './readme-badges.mjs';
 import { DECLARATION } from './sonar-key.mjs';
@@ -19,7 +20,7 @@ export function hasDeclaredServices(root, { parseYaml = bundledParseYaml } = {})
 export function readDeclaredQuality(root, { parseYaml = bundledParseYaml } = {}) {
     try {
         const doc = parseYaml(fs.readFileSync(path.join(root, DECLARATION), 'utf8'));
-        return qualityServices(doc, { example: isRuntimeExampleApp(root) });
+        return qualityServices(doc, { example: isRuntimeExampleApp(root), repository: repositoryName(root, { env: identityQueryEnvironment(process.env, serviceCredentialNames(doc)) }) });
     }
     catch {
         return qualityServices({});

package/sync/readme-badges.mjs

@@ -17,7 +17,7 @@ export function renderReadmeBadges(doc, { repository, example = false } = {}) {
     const branch = encodeURIComponent(github.defaultBranch ?? 'main');
     const workflow = encodeURIComponent(github.workflow ?? 'ci.yml');
     const base = `https://github.com/${repo}`;
-    const quality = qualityServices(doc, { example });
+    const quality = qualityServices(doc, { example, repository: repo.split('/')[1] });
     const lines = [badge('CI', `${base}/actions/workflows/${workflow}/badge.svg?branch=${branch}`, `${base}/actions/workflows/${workflow}`)];
     if (quality.codecov.enabled) {
         const params = [];

package/sync/sonar-key.d.mts

@@ -1,9 +1,9 @@
+import { repositoryName } from '../runtime/scripts/hfs/repo-identity.mjs';
+export { repositoryName };
 type Declaration = any;
 type ParseYaml = (text: string) => Declaration;
 /** The stack declaration, app-relative: .starcistacks sits at the app root, beside be/, fe/ and .starciwork. */
 export declare const DECLARATION: string;
-/** The repository name the declaration lists its projects under: the app package.json name, else the folder name. */
-export declare function repositoryName(root: string): string;
 /** The keys services.sonar declares for `repository` in a parsed declaration (empty when it declares none). */
 export declare function declaredSonarKeys(declaration: Declaration, repository: string): string[];
 /**
@@ -28,4 +28,3 @@ export declare function readDeclaredSonarGate(root: string, { parseYaml }?: {
 } | null;
 /** The quality-gate name for an app edition from the one sonar-gate document. */
 export declare function sonarGateName(document: Declaration, edition?: string): string | null;
-export {};

package/sync/sonar-key.mjs

@@ -4,20 +4,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
+import { repositoryName, identityQueryEnvironment } from '../runtime/scripts/hfs/repo-identity.mjs';
+import { serviceCredentialNames } from '../runtime/scripts/hfs/ci-declaration.mjs';
+export { repositoryName };
 /** The stack declaration, app-relative: .starcistacks sits at the app root, beside be/, fe/ and .starciwork. */
 export const DECLARATION = path.join('.starcistacks', 'application-stacks.yaml');
-/** The repository name the declaration lists its projects under: the app package.json name, else the folder name. */
-export function repositoryName(root) {
-    try {
-        const name = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name;
-        if (typeof name === 'string' && name)
-            return name;
-    }
-    catch {
-        // no readable package.json: the folder name stands in
-    }
-    return path.basename(path.resolve(root));
-}
 /** The keys services.sonar declares for `repository` in a parsed declaration (empty when it declares none). */
 export function declaredSonarKeys(declaration, repository) {
     const projects = declaration?.services?.sonar?.projects;
@@ -35,9 +26,11 @@ export async function readDeclaredSonarKey(root, { parseYaml, fail }) {
     if (!fs.existsSync(file))
         return null;
     const parse = parseYaml ?? bundledParseYaml;
-    const keys = declaredSonarKeys(parse(fs.readFileSync(file, 'utf8')), repositoryName(root));
+    const doc = parse(fs.readFileSync(file, 'utf8'));
+    const repository = repositoryName(root, { env: identityQueryEnvironment(process.env, serviceCredentialNames(doc)) });
+    const keys = declaredSonarKeys(doc, repository);
     if (keys.length > 1)
-        fail(`${DECLARATION.split(path.sep).join('/')} declares ${keys.length} Sonar projects for ${repositoryName(root)} (${keys.join(', ')}); one app has one key`);
+        fail(`${DECLARATION.split(path.sep).join('/')} declares ${keys.length} Sonar projects for ${repository} (${keys.join(', ')}); one app has one key`);
     return keys[0] ?? null;
 }
 /**