@starci/hfs 5.2.0 → 5.4.0

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

@@ -1,4 +1,4 @@
-// R255-R256 inspect the final database access state: the application role, forced RLS, policies, views and storage prefixes.
+// R255-R256 inspect the final database access state: the application role (its attributes and every grant on schema auth), forced RLS, policies, views and storage prefixes.
 import { found } from './read.mjs';
 import { parseSql } from '../sql/pg-parse.mjs';
 import { eachInOrder } from '../../lib/in-order.mjs';
@@ -20,6 +20,10 @@ const AND = ['AND', 'EXPR'].join('_');
 const OR = ['OR', 'EXPR'].join('_');
 const NOT = ['NOT', 'EXPR'].join('_');
 const SEQUENCE = ['OBJECT', 'SEQUENCE'].join('_');
+const SCHEMA = ['OBJECT', 'SCHEMA'].join('_');
+const TABLE = ['OBJECT', 'TABLE'].join('_');
+const ALL_IN_SCHEMA = ['ACL', 'TARGET', 'ALL', 'IN', 'SCHEMA'].join('_');
+const ACCOUNT_SCHEMA = 'auth';
 const MATVIEW = ['OBJECT', 'MATVIEW'].join('_');
 const note = (code, source, message, extra = {}) => found(code, source.file, `${source.file}:${source.line} ${message}`, { line: source.line, ...extra });
 function someNode(node, predicate) {
@@ -157,6 +161,39 @@ function roleFindings(analyses, appRole) {
     }
     return findings;
 }
+/** What one grant statement names inside schema auth: the schema, a table or sequence of it, every table or sequence in it. */
+function authTargets(grant) {
+    if (grant.objtype === SCHEMA)
+        return grant.objects.filter((object) => sval(object) === ACCOUNT_SCHEMA).map(() => `schema ${ACCOUNT_SCHEMA}`);
+    if (![TABLE, SEQUENCE].includes(grant.objtype))
+        return [];
+    if (grant.targtype === ALL_IN_SCHEMA)
+        return grant.objects.filter((object) => sval(object) === ACCOUNT_SCHEMA).map(() => `all ${grant.objtype === TABLE ? 'tables' : 'sequences'} in schema ${ACCOUNT_SCHEMA}`);
+    return grant.objects.filter((object) => object.RangeVar?.schemaname === ACCOUNT_SCHEMA).map((object) => relationName(object.RangeVar));
+}
+/**
+ * R255: the application role holds no privilege on schema auth, on a table or sequence in it, or by default privilege for the
+ * schema. The migrations are applied in order, so a grant that a later migration revokes (the contract step of an app that moved
+ * to the identity account doors) is not held; what remains at the end is reported at the grant that left it.
+ */
+function authSchemaFindings(analyses, appRole) {
+    const held = new Map();
+    for (const { file, facts } of analyses) {
+        const statements = [
+            ...facts.grants.map((grant) => ({ grant, targets: authTargets(grant) })),
+            ...facts.defaultPrivileges.map((grant) => ({ grant, targets: grant.schemas.includes(ACCOUNT_SCHEMA) ? [`default privileges in schema ${ACCOUNT_SCHEMA}`] : [] })),
+        ].filter(({ grant }) => grant.grantees.includes(appRole));
+        for (const { grant, targets } of statements) {
+            for (const target of targets) {
+                const state = held.get(target) ?? { target, privileges: new Set() };
+                updatePrivileges(state, grant.grant, grant.all ? ['all'] : grant.privileges);
+                held.set(target, { ...state, file, line: grant.line });
+            }
+        }
+    }
+    return [...held.values()].filter((state) => state.privileges.size > 0)
+        .map((state) => note(DB_APP_ROLE, state, `${appRole} holds a grant on ${state.target}; reach accounts through the identity account doors (SECURITY DEFINER functions), never through a grant on schema ${ACCOUNT_SCHEMA}; an app on the old sign-in glue runs "starci app codemod account-doors", "starci app sync --execute" and "starci app codemod account-doors --contract" in one release`, { target: state.target }));
+}
 function roleStatementFindings(statement, appRole) {
     const { type, node } = statement;
     if (!['CreateRoleStmt', 'AlterRoleStmt'].includes(type))
@@ -299,6 +336,7 @@ export async function databaseAccessFindings({ analyses, exposed, db = {} }) {
     return [
         ...policyFindings(policies, appRole, helpers),
         ...roleFindings(analyses, appRole),
+        ...authSchemaFindings(analyses, appRole),
         ...forceFindings(analyses, declared, appRole),
         ...viewFindings(analyses, grants, exposed),
         ...storagePrefixFindings(policies, helpers),

package/runtime/scripts/hfs/rules/monorepo.d.mts

@@ -1,6 +1,10 @@
 import type { Parsed, Repo } from './rule-types.mjs';
 /** The npm workspaces of every app, in this order. */
 export declare const WORKSPACES: readonly string[];
+/** The workspace of the app's own root packages (slot app.packages: packages/agent-sdk, packages/module-<name>), added after the fe ones once one is tracked. */
+export declare const ROOT_PACKAGES_WORKSPACE = "packages/*";
+/** The workspaces the tracked tree `files` calls for: the fe ones, then `packages/*` when a root package tracks its package.json. */
+export declare const workspacesFor: (files: readonly string[]) => readonly string[];
 /** The scripts of every fe app workspace, exactly: turbo runs build, dev and typecheck; start serves a build. The lint is the root's (`starci app check --gate lint`), never a workspace script. */
 export declare const FE_APP_SCRIPTS: Readonly<Record<string, string>>;
 /** The package manager every app root declares (turbo reads it to parse the lockfile); the starci app scaffold writes it. */

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

@@ -1,6 +1,6 @@
 // monorepo.mjs - every product is a monorepo, even a single app: the app root holds one package.json and lockfile whose npm
 // workspaces are the fe apps and packages (turbo runs their tasks), and the back end is a Nest monorepo of be/apps/<app>.
-//   HFS_MONO_WORKSPACES          the root package.json: `workspaces` exactly fe/apps/* and fe/packages/*, `packageManager` npm at an
+//   HFS_MONO_WORKSPACES          the root package.json: `workspaces` exactly fe/apps/* and fe/packages/* (and packages/* once the app tracks a root workspace package, slot app.packages), `packageManager` npm at an
 //                                exact version, turbo a root devDependency (its version is the canon pin); turbo.json is app.task-graph
 //   HFS_MONO_FE_WORKSPACE        every fe app's package.json is @<project>/<app>, private, with exactly the workspace scripts; every
 //                                fe package's package.json is private with build and typecheck scripts and the workspace lint
@@ -22,6 +22,10 @@ const MONO_NEST_PROJECTS = 'HFS_MONO_NEST_PROJECTS';
 const MONO_WORKSPACE_DEP = 'HFS_MONO_WORKSPACE_DEP';
 /** The npm workspaces of every app, in this order. */
 export const WORKSPACES = Object.freeze(['fe/apps/*', 'fe/packages/*']);
+/** The workspace of the app's own root packages (slot app.packages: packages/agent-sdk, packages/module-<name>), added after the fe ones once one is tracked. */
+export const ROOT_PACKAGES_WORKSPACE = 'packages/*';
+/** The workspaces the tracked tree `files` calls for: the fe ones, then `packages/*` when a root package tracks its package.json. */
+export const workspacesFor = (files) => (files.some((file) => /^packages\/[^/]+\/package\.json$/.test(file)) ? [...WORKSPACES, ROOT_PACKAGES_WORKSPACE] : WORKSPACES);
 /** The scripts of every fe app workspace, exactly: turbo runs build, dev and typecheck; start serves a build. The lint is the root's (`starci app check --gate lint`), never a workspace script. */
 export const FE_APP_SCRIPTS = Object.freeze({ build: 'next build', dev: 'next dev', start: 'next start', typecheck: 'tsc --noEmit' });
 /** The scripts every fe package workspace has (its build and typecheck commands are its own); it has no lint script. */
@@ -49,13 +53,14 @@ function workspacesOf(files) {
     return [...folders].sort(byCodeUnit);
 }
 /** R143: the root package.json declares the workspaces, the package manager and turbo. */
-function rootFindings(repoRoot) {
+function rootFindings(repoRoot, files) {
     const pkg = readJson(repoRoot, MANIFEST);
     if (!pkg)
         return [];
     const findings = [];
-    if (!sameList(pkg.workspaces, WORKSPACES))
-        findings.push(found(MONO_WORKSPACES, MANIFEST, `${MANIFEST} declares workspaces ${JSON.stringify(pkg.workspaces ?? null)}; every app is a monorepo whose npm workspaces are exactly ${JSON.stringify(WORKSPACES)} (each fe app and package has its own package.json; be has none).`, { workspaces: pkg.workspaces ?? null }));
+    const wanted = workspacesFor(files);
+    if (!sameList(pkg.workspaces, wanted))
+        findings.push(found(MONO_WORKSPACES, MANIFEST, `${MANIFEST} declares workspaces ${JSON.stringify(pkg.workspaces ?? null)}; every app is a monorepo whose npm workspaces are exactly ${JSON.stringify(wanted)} (each fe app and package has its own package.json; be has none; ${ROOT_PACKAGES_WORKSPACE} is listed when the app tracks a root package).`, { workspaces: pkg.workspaces ?? null }));
     if (!PACKAGE_MANAGER_FORM.test(String(pkg.packageManager ?? '')))
         findings.push(found(MONO_WORKSPACES, MANIFEST, `${MANIFEST} declares packageManager ${JSON.stringify(pkg.packageManager ?? null)}; turbo needs \`npm@<exact version>\` there.`, { packageManager: pkg.packageManager ?? null }));
     if (typeof pkg.devDependencies?.turbo !== 'string')
@@ -234,7 +239,7 @@ export function monorepoFindings({ repoRoot, files, repo }) {
     const workspaces = workspacesOf(files);
     const beApps = repo.sides.be.apps;
     return [
-        ...rootFindings(repoRoot),
+        ...rootFindings(repoRoot, files),
         ...workspaceManifestFindings(repoRoot, repo.project, workspaces),
         ...nestFindings(repoRoot, files, beApps),
         ...workspaceDepFindings(repoRoot, files, workspaces),

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

@@ -8,6 +8,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { FORBIDDEN_FILES, secretHitsInFile } from '../../lib/secret-patterns.mjs';
+import { SECRETS_CACHE_FILE, secretRecordFaults } from '../../lib/secret-records.mjs';
 import { isSopsEnvelope } from '../../lib/sops-envelope.mjs';
 import { found, readText } from './read.mjs';
 const PLAINTEXT_SECRET = 'HFS_PLAINTEXT_SECRET';
@@ -28,6 +29,14 @@ export function untrackedSecretFindings({ repoRoot, files, repo }) {
     }
     return [found(PLAINTEXT_SECRET, 'secrets.env', 'secrets.env is an untracked plaintext secret at the lite app root; seal it with starci app secret set --env <env> into .starcistacks/<env>/secrets/<slug>.enc and remove the plaintext file; read materialized values by *_FILE', { level: 'warning', pattern: 'untracked-secrets-env' })];
 }
+/** The findings of a file of the committed secrets cache: it is judged by what it holds (codes, paths, positions and digests, secret-records.mjs), never by the `secrets/` folder it sits in. */
+function cacheRecordFindings(file, text) {
+    const faults = secretRecordFaults(text);
+    if (faults.length === 0)
+        return [];
+    const more = faults.length > 1 ? ` (and ${faults.length - 1} more)` : '';
+    return [found(PLAINTEXT_SECRET, file, `${file}: ${faults[0]}${more}; the secrets cache holds codes, paths, positions and digests only, so a file that holds more may carry secret material; regenerate it with starci app check --gate secrets, or migrate it with starci app codemod secrets-cache --execute`, { pattern: 'secrets-cache-record' })];
+}
 /**
  * The findings of R06 for one tracked file that no forbidden slot claims: a secret by being (an env file, a key file), an `.enc` that is
  * no sops envelope, or a line that matches a secret pattern. `text` is the file's text, or null when it cannot be read (binary, too
@@ -39,6 +48,8 @@ export function secretFileFindings({ file, text, manifestText }) {
         return [found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret by being (${being.name}); a secret is committed only as a sops envelope at .starcistacks/<env>/secrets/<slug>.enc`, { pattern: being.name })];
     if (text === null || text === undefined || NOT_SCANNED.test(file))
         return [];
+    if (SECRETS_CACHE_FILE.test(file))
+        return cacheRecordFindings(file, text);
     if (/\.enc(?:\.yaml)?$/.test(file))
         return isSopsEnvelope(text) ? [] : [found(PLAINTEXT_SECRET, file, `${file} is named like a sealed secret but is not a sops envelope; encrypt the value with sops and commit only the envelope`, { pattern: 'sops-not-envelope' })];
     const findings = [];

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

@@ -1,4 +1,7 @@
+/** A refusal with a message safe to print; `code` names it when a caller or a spec keys on it. */
 export declare class SecretError extends Error {
+    code: string | undefined;
+    constructor(message: string, code?: string);
 }
 export declare const publicStorage: <T>(action: () => T) => T;
 export declare function secretErrorMessage(caught: unknown): string;

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

@@ -1,11 +1,19 @@
 // secret-errors.mjs - sanitized public errors shared by app secret operations.
+/** A refusal with a message safe to print; `code` names it when a caller or a spec keys on it. */
 export class SecretError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
 }
 export const publicStorage = (action) => {
     try {
         return action();
     }
     catch (caught) {
+        if (caught instanceof SecretError)
+            throw caught;
         // reason: a thrown value is untyped; storage failures are Node errors carrying an optional code.
         const error = caught;
         throw new SecretError(error.code ? `private storage failed (${error.code})` : error.message);

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

@@ -72,6 +72,12 @@ export declare function decryptionIdentity(repoRoot: string, env: NodeJS.Process
 export declare function ageIdentityEnv(repoRoot: string, env: NodeJS.ProcessEnv, tools?: SecretToolOverrides): NodeJS.ProcessEnv;
 /** Select the first matching public age rule, including for SOPS's isolated CI identity path. */
 export declare function configuredRecipients(repoRoot: string, file: string): string[];
+/**
+ * Whether sops itself finds a creation rule for `file`: the first rule whose path_regex matches the path as written (sops reads the file's own
+ * name, so a `.enc.yaml` member is not matched by a rule written for the legacy `.enc` spelling, which configuredRecipients tolerates when it
+ * only reads recipients). A rule with no path_regex matches everything.
+ */
+export declare function sopsFindsRule(repoRoot: string, file: string): boolean;
 /** Resolve required tools without exposing subprocess output (which can contain private data). */
 export declare function secretTools(env: NodeJS.ProcessEnv, tools?: SecretToolOverrides): SecretTools;
 /**

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

@@ -154,6 +154,29 @@ export function configuredRecipients(repoRoot, file) {
         throw new Error(".sops.yaml must supply public age recipients for this secret; run starci app secret init");
     return recipients;
 }
+/**
+ * Whether sops itself finds a creation rule for `file`: the first rule whose path_regex matches the path as written (sops reads the file's own
+ * name, so a `.enc.yaml` member is not matched by a rule written for the legacy `.enc` spelling, which configuredRecipients tolerates when it
+ * only reads recipients). A rule with no path_regex matches everything.
+ */
+export function sopsFindsRule(repoRoot, file) {
+    let config; // reason: parsed YAML boundary, read from disk
+    try {
+        config = parseYaml(fs.readFileSync(path.join(repoRoot, ".sops.yaml"), "utf8"));
+    }
+    catch {
+        return false;
+    }
+    const relative = path.relative(repoRoot, file).split(path.sep).join("/");
+    return (config?.creation_rules ?? []).some((entry) => {
+        try {
+            return !entry.path_regex || new RegExp(entry.path_regex).test(relative) || new RegExp(entry.path_regex).test(relative.replaceAll("/", "\\"));
+        }
+        catch {
+            return false;
+        }
+    });
+}
 /** Resolve required tools without exposing subprocess output (which can contain private data). */
 export function secretTools(env, tools = {}) {
     const sops = (tools.resolveSops ?? resolveSops)(env);

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

@@ -10,7 +10,7 @@ import { updateKeys as sopsUpdateKeys } from "../api/sops/update-keys.mjs";
 import { isLegacyName } from "../lib/sealed-member.mjs";
 import { invocationDir } from "../lib/roots.mjs";
 import { envelopeOf } from "./secret-document.mjs";
-import { configuredRecipients, decryptionIdentity, secretTools, } from "./secret-init.mjs";
+import { configuredRecipients, sopsFindsRule, decryptionIdentity, secretTools, } from "./secret-init.mjs";
 import { outsideRepository } from "./secret-files.mjs";
 import { SecretError, publicStorage } from "./secret-errors.mjs";
 const sopsInvocation = Object.freeze({ runProgram, resolveRealTool });
@@ -83,9 +83,17 @@ function identityMissing(repoRoot, identity, file) {
  * the existing member is sealed to, so no rewrite (set, migrate, split, an edit) drops a recipient such as the deploy server's.
  * `ruled` says whether a rule of the app's .sops.yaml matches the file. Refused, as the rule refuses, when none names one.
  */
+/** The refusal for a member no creation rule of `.sops.yaml` reaches, naming the path and the way to the per-environment rules. */
+function unruledMessage(repoRoot, file) {
+    const relative = path.relative(repoRoot, file).split(path.sep).join("/");
+    const environment = /^\.starcistacks\/([^/]+)\//.exec(relative)?.[1] ?? "<env>";
+    return `SECRET_SOPS_RULE_MISSING: no creation rule of .sops.yaml matches ${relative} (a rule written for the legacy .enc spelling does not match .enc.yaml), so sops cannot seal it; run starci app secret init --env ${environment}, which writes the per-environment rules, or starci app codemod sops-rules --execute to migrate the file`;
+}
 function sealRecipients(repoRoot, file, named) {
     try {
         const rule = configuredRecipients(repoRoot, file);
+        if (!sopsFindsRule(repoRoot, file))
+            throw new SecretError(unruledMessage(repoRoot, file), "SECRET_SOPS_RULE_MISSING");
         return { recipients: named.length ? named : rule, ruled: true };
     }
     catch (error) {

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

@@ -59,6 +59,25 @@ export declare function sshTransportMembers(spec: EnvironmentSpec | undefined):
  * RECIPIENT_DRIFT, UNDECLARED_KEY (only where application-stacks.yaml declares the environment), UNTRACKED. Names only.
  */
 export declare function auditSecrets(repoRoot: string, environment?: string | null): AuditFinding[];
+/** What `secret set` did with a member that is a service credential (tooling, never an app runtime secret): the keys it bound, or the remedy to apply by hand. */
+export interface ToolingOutcome {
+    bound: string[];
+    remedy: string;
+}
+/** One sealed tooling member `bindToolingMembers` judged: what it bound, the remedy when it could not, and the runtime entries an earlier `secret set` declared for it. */
+export interface ToolingMember {
+    environment: string;
+    member: string;
+    service: string;
+    outcome: ToolingOutcome;
+    runtimeEntries: string[];
+}
+/**
+ * The tooling members of the app (a sealed `.starcistacks/<env>/secrets/<member>.enc.yaml` that a service of application-stacks.yaml owns): each is bound
+ * to its service when `write` and the binding is missing in the shape the template renders. The runtime `secrets:` entries an earlier `secret set` declared for
+ * the member are named, not removed: the owner deletes them (CI custody refuses the token while one stands).
+ */
+export declare function bindToolingMembers(repoRoot: string, write: boolean): ToolingMember[];
 /**
  * Declares each of `keys` of `member` in environment `environment`'s `secrets:` of application-stacks.yaml, one entry per key
  * (`name: <kebab of the key>, member, key, where: secrets/<member>`), so the key is materialized as its own `<KEY>_FILE`. A key
@@ -68,6 +87,7 @@ export declare function auditSecrets(repoRoot: string, environment?: string | nu
 export declare function declareKeys(repoRoot: string, environment: string, member: string, keys: string[]): {
     declared: string[];
     byHand: string[];
+    tooling?: ToolingOutcome;
 };
 /**
  * Records `recipient` as `environments.<environment>.deploy.remote.serverRecipient` of application-stacks.yaml: the public age

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

@@ -160,6 +160,107 @@ function childLine(lines, block, key) {
             return at;
     return -1;
 }
+/** The service of `services:` that `member` is the sealed credential of: named like the member (`sonar`), or one whose credential custody path is the member's file. */
+function toolingServiceOf(document, member) {
+    const services = (document["services"] ?? {});
+    for (const [name, service] of Object.entries(services)) {
+        if (service === null || typeof service !== "object")
+            continue;
+        const owns = (service.credentials ?? []).some((credential) => new RegExp(`/${member}\\.enc(?:\\.yaml)?$`, "u").test(credential?.custody?.path ?? ""));
+        if (name === member || owns)
+            return { name, service };
+    }
+    return null;
+}
+/**
+ * A tooling member (sonar.enc.yaml: the analysis token a CI job reads) is a credential of a service, not a secret the app reads at runtime, so it never
+ * becomes an `environments.<env>.secrets` entry (CI custody refuses a runtime-granted CI secret, APP_SECRET_IN_CI). Its binding is the service's
+ * `credentials` entry (custody names the sealed file) and the `ci.secrets` entry that reads it. A missing binding of the shape the template renders
+ * (`credentials: []`) is written; any other shape returns the exact binding to add by hand.
+ */
+function bindTooling(file, text, document, repository, environment, member, keys, found) {
+    const bound = new Set((found.service.credentials ?? []).map((credential) => credential.key));
+    const missing = keys.filter((key) => !bound.has(key));
+    if (!missing.length)
+        return { bound: [], remedy: "" };
+    const project = found.service.projects?.[0]?.key ?? repository;
+    const custodyPath = `.starcistacks/${environment}/secrets/${member}.enc.yaml`;
+    const first = !(found.service.credentials ?? []).length;
+    const credentials = missing.map((key, index) => ({ id: first && index === 0 ? "analysis" : key.toLowerCase().replaceAll("_", "-"), project, key, custody: { repository, path: custodyPath } }));
+    const ciSecrets = credentials.map((credential) => ({ name: credential.key, credential: credential.id }));
+    const remedy = `${member} is a tooling credential of services.${found.name}, not an app runtime secret, so it is not declared in environments.${environment}.secrets; bind it by hand: services.${found.name}.credentials: ${JSON.stringify(credentials)} and services.${found.name}.ci.secrets: ${JSON.stringify(ciSecrets)}`;
+    const newline = text.includes("\r\n") ? "\r\n" : "\n";
+    const lines = text.replace(/\r\n/gu, "\n").split("\n");
+    const root = lines.findIndex((line) => /^services:\s*(?:#.*)?$/u.test(line));
+    const serviceLine = root < 0 ? -1 : childLine(lines, blockOf(lines, root), found.name);
+    const credentialsLine = serviceLine < 0 ? -1 : childLine(lines, blockOf(lines, serviceLine), "credentials");
+    if (credentialsLine < 0 || !/^ *credentials:\s*\[\s*\]\s*(?:#.*)?$/u.test(lines[credentialsLine]) || !first)
+        return { bound: [], remedy };
+    const pad = indentOf(lines[credentialsLine]);
+    const ciLine = childLine(lines, blockOf(lines, serviceLine), "ci");
+    const expected = structuredClone(document);
+    const target = expected["services"][found.name];
+    target.credentials = credentials;
+    if (target.ci !== undefined)
+        target.ci.secrets = [...(target.ci.secrets ?? []), ...ciSecrets];
+    if (target.ci !== undefined) {
+        const ci = ciLine < 0 ? "" : lines[ciLine];
+        const secrets = `[${ciSecrets.map((entry) => `{name: ${entry.name}, credential: ${entry.credential}}`).join(", ")}]`;
+        if (/secrets:\s*\[\s*\]/u.test(ci))
+            lines[ciLine] = ci.replace(/secrets:\s*\[\s*\]/u, `secrets: ${secrets}`);
+        else if (/^ *ci:\s*\{.*\}\s*$/u.test(ci) && !/secrets:/u.test(ci))
+            lines[ciLine] = ci.replace(/\}\s*$/u, `, secrets: ${secrets}}`);
+        else
+            return { bound: [], remedy };
+    }
+    const block = credentials.flatMap((credential) => [`${" ".repeat(pad + 2)}- id: ${credential.id}`, `${" ".repeat(pad + 4)}project: ${JSON.stringify(credential.project)}`, `${" ".repeat(pad + 4)}key: ${credential.key}`, `${" ".repeat(pad + 4)}custody: {repository: ${JSON.stringify(credential.custody.repository)}, path: ${credential.custody.path}}`]);
+    lines.splice(credentialsLine, 1, `${" ".repeat(pad)}credentials:`, ...block);
+    const edited = lines.join(newline);
+    let parsed;
+    try {
+        parsed = parseYaml(edited);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (JSON.stringify(parsed) !== JSON.stringify(expected))
+        return { bound: [], remedy };
+    fs.writeFileSync(file, edited);
+    return { bound: missing, remedy: "" };
+}
+/**
+ * The tooling members of the app (a sealed `.starcistacks/<env>/secrets/<member>.enc.yaml` that a service of application-stacks.yaml owns): each is bound
+ * to its service when `write` and the binding is missing in the shape the template renders. The runtime `secrets:` entries an earlier `secret set` declared for
+ * the member are named, not removed: the owner deletes them (CI custody refuses the token while one stands).
+ */
+export function bindToolingMembers(repoRoot, write) {
+    const file = path.join(repoRoot, ".starcistacks", "application-stacks.yaml");
+    if (!fs.existsSync(file))
+        return [];
+    const text = fs.readFileSync(file, "utf8");
+    const document = parseYaml(text) ?? {}; // reason: parsed YAML boundary, read from disk
+    const repository = repositoryName(repoRoot, { env: identityQueryEnvironment(process.env, serviceCredentialNames(document)) });
+    const found = [];
+    for (const environment of Object.keys(document.environments ?? {})) {
+        const directory = path.join(repoRoot, ".starcistacks", environment, "secrets");
+        if (!fs.existsSync(directory))
+            continue;
+        for (const name of fs.readdirSync(directory).filter((entry) => entry.endsWith(MEMBER_SUFFIX)).sort()) {
+            const member = name.slice(0, -MEMBER_SUFFIX.length);
+            const service = toolingServiceOf(document, member);
+            if (service === null)
+                continue;
+            const keys = envelopeOf(fs.readFileSync(path.join(directory, name), "utf8")).keys;
+            const entries = Array.isArray(document.environments?.[environment]?.secrets) ? document.environments?.[environment]?.secrets : [];
+            const runtimeEntries = entries.filter((entry) => memberOfEntry(entry) === member).map((entry) => String(entry.name ?? entry.key ?? member));
+            const outcome = write
+                ? bindTooling(file, fs.readFileSync(file, "utf8"), parseYaml(fs.readFileSync(file, "utf8")) ?? {}, repository, environment, member, keys, service)
+                : { bound: [], remedy: (service.service.credentials ?? []).length ? "" : `services.${service.name} has no credential for ${member}` };
+            found.push({ environment, member, service: service.name, outcome, runtimeEntries });
+        }
+    }
+    return found;
+}
 /**
  * Declares each of `keys` of `member` in environment `environment`'s `secrets:` of application-stacks.yaml, one entry per key
  * (`name: <kebab of the key>, member, key, where: secrets/<member>`), so the key is materialized as its own `<KEY>_FILE`. A key
@@ -175,6 +276,11 @@ export function declareKeys(repoRoot, environment, member, keys) {
     const spec = document.environments?.[environment];
     if (!spec)
         return { declared: [], byHand: [] };
+    const tooling = toolingServiceOf(document, member);
+    if (tooling !== null) {
+        const outcome = bindTooling(file, text, document, repositoryName(repoRoot, { env: identityQueryEnvironment(process.env, serviceCredentialNames(document)) }), environment, member, keys, tooling);
+        return outcome.bound.length || outcome.remedy ? { declared: [], byHand: [], tooling: outcome } : { declared: [], byHand: [] };
+    }
     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)

package/runtime/scripts/hfs/secret.mjs

@@ -193,7 +193,11 @@ function fromFiles(entries, keys) {
     return files;
 }
 /** What `set` declared in the environment's stack `secrets:`, or the keys to declare by hand; nothing when all were declared. */
-function declarationLine(environment, { declared, byHand }) {
+function declarationLine(environment, { declared, byHand, tooling }) {
+    if (tooling?.bound.length)
+        return `bound ${tooling.bound.join(", ")} to the service credentials and ci.secrets of application-stacks.yaml (a tooling member is not a runtime secret)\n`;
+    if (tooling?.remedy)
+        return `${tooling.remedy}\n`;
     if (declared.length)
         return `declared ${declared.join(", ")} in environments.${environment}.secrets of application-stacks.yaml\n`;
     if (byHand.length)

package/runtime/scripts/hfs/view.d.mts

@@ -43,3 +43,26 @@ export declare const declaredHfsView: ({ runtimeRoot, declaration, repoRoot, sid
     repoRoot: string;
     side: string;
 }) => HfsView;
+/**
+ * The view of the root packages of the app at `repoRoot` (the app root, where the root `eslint.config.mjs` lives), for the laws of `side`.
+ *
+ * @param {{ runtimeRoot: string, repoRoot: string, side: string }} input - Where the manifest copy lives, the app root, and the side whose laws apply.
+ * @returns {object} The frozen view.
+ */
+export declare const openPackagesHfsView: ({ runtimeRoot, repoRoot, side }: {
+    runtimeRoot: string;
+    repoRoot: string;
+    side: "be" | "fe";
+}) => HfsView;
+/**
+ * The view of the root packages of an in-memory app declaration (rule tests): no file is read except the manifest.
+ *
+ * @param {{ runtimeRoot: string, declaration: object, repoRoot: string, side: string }} input - Manifest root, the app hfs.json object, the app root and the side.
+ * @returns {object} The frozen view.
+ */
+export declare const declaredPackagesHfsView: ({ runtimeRoot, declaration, repoRoot, side }: {
+    runtimeRoot: string;
+    declaration: Parsed;
+    repoRoot: string;
+    side: "be" | "fe";
+}) => HfsView;

package/runtime/scripts/hfs/view.mjs

@@ -5,6 +5,7 @@
 import path from 'node:path';
 import { allowsFile } from './allows.mjs';
 import { openHfs } from './slots.mjs';
+import { ROOT_PACKAGE_SLOTS } from './architecture/root-packages.mjs';
 const posix = (p) => String(p).replaceAll('\\', '/');
 const isAbsoluteAny = (text) => path.isAbsolute(text) || /^[A-Za-z]:\//.test(text);
 /**
@@ -69,3 +70,70 @@ export const openHfsView = ({ runtimeRoot, repoRoot }) => hfsView(openHfs({ root
  * @returns {object} The frozen view.
  */
 export const declaredHfsView = ({ runtimeRoot, declaration, repoRoot, side }) => hfsView(openHfs({ root: runtimeRoot, declaration, side }), repoRoot);
+/**
+ * The view of the root workspace packages of an app (`packages/<pkg>/src/**`, slots app.packages and app.module-registry), as the lint of one
+ * side sees them: the rule parameters, the apps and the Grammar of `side` (a package is judged by the laws of the side whose subpath a file
+ * sits in), and the paths of the APP ROOT (`repoRoot` is the app root, not a side folder). The slots answer for the root paths; a file of a
+ * package is of the tier `package` and has no owner: the owner laws (one `index.ts` per owner root) are the module folders', a package's public
+ * surface being the `exports` of its manifest.
+ *
+ * @param {object} opened - The result of `openHfs` for the app root (profile app, both sides resolved).
+ * @param {string} repoRoot - The absolute app root.
+ * @param {string} side - `be` or `fe`: the side whose laws the file is judged by.
+ * @returns {object} The frozen view: the profile of the side over the paths of the app root.
+ */
+function packagesView(opened, repoRoot, side) {
+    const scope = opened.sides?.[side];
+    const sideRepo = opened.repo.sides?.[side];
+    if (scope === undefined || sideRepo === undefined)
+        throw new Error('the view of the root packages needs the declaration of an app with both sides');
+    const rel = (file) => {
+        const text = posix(file);
+        return isAbsoluteAny(text) ? posix(path.relative(repoRoot, file)) : text.replace(/^\.\//, '');
+    };
+    const cache = new Map();
+    const classify = (file) => {
+        const key = rel(file);
+        if (!cache.has(key))
+            cache.set(key, opened.classifyPath(key));
+        return cache.get(key);
+    };
+    const packageOf = (file) => {
+        const slot = classify(file).slot;
+        const relative = rel(file);
+        return slot !== undefined && ROOT_PACKAGE_SLOTS.has(slot) ? relative.split('/').slice(0, 2).join('/') : null;
+    };
+    return Object.freeze({
+        repoRoot,
+        profile: side,
+        side,
+        edition: opened.repo.edition ?? 'full',
+        ...(sideRepo.grammar === undefined ? {} : { grammar: sideRepo.grammar }),
+        apps: sideRepo.apps,
+        connections: sideRepo.connections,
+        patterns: Object.freeze([...(sideRepo.patterns ?? [])]),
+        ruleParams: scope.ruleParams(),
+        relative: rel,
+        classify,
+        slotOf: (file) => classify(file).slot ?? null,
+        tierOf: (file) => (packageOf(file) === null ? null : 'package'),
+        // A package is no owner of the module laws (one index.ts at the owner root): its public surface is the `exports` of its manifest, so no file of it has an owner.
+        ownerOf: () => null,
+        allows: (file) => allowsFile(opened, rel(file)),
+        slot: (id) => opened.slot(id),
+    });
+}
+/**
+ * The view of the root packages of the app at `repoRoot` (the app root, where the root `eslint.config.mjs` lives), for the laws of `side`.
+ *
+ * @param {{ runtimeRoot: string, repoRoot: string, side: string }} input - Where the manifest copy lives, the app root, and the side whose laws apply.
+ * @returns {object} The frozen view.
+ */
+export const openPackagesHfsView = ({ runtimeRoot, repoRoot, side }) => packagesView(openHfs({ root: runtimeRoot, repoRoot }), repoRoot, side);
+/**
+ * The view of the root packages of an in-memory app declaration (rule tests): no file is read except the manifest.
+ *
+ * @param {{ runtimeRoot: string, declaration: object, repoRoot: string, side: string }} input - Manifest root, the app hfs.json object, the app root and the side.
+ * @returns {object} The frozen view.
+ */
+export const declaredPackagesHfsView = ({ runtimeRoot, declaration, repoRoot, side }) => packagesView(openHfs({ root: runtimeRoot, declaration }), repoRoot, side);

package/runtime/scripts/lib/declaration-surface.d.mts

@@ -26,6 +26,10 @@ export declare const DECLARATION: RegExp;
 export declare const TYPESCRIPT: RegExp;
 /** Whether `file` is a TypeScript source (not a declaration file) the declaration emit reads. */
 export declare const isEmittableSource: (file: string) => boolean;
+/** The package whose module-definition helpers return a type they state in their own declaration (R368 accepts a destructured export of their call). */
+export declare const STATED_SURFACE_PACKAGE = "@starci/nest-kit";
+/** The helpers of that package: each is called with the options type as a type argument and returns the explicitly typed definition. */
+export declare const STATED_SURFACE_HELPERS: ReadonlySet<string>;
 /**
  * The declaration emit of one TypeScript source and the exports it could not write explicitly (a type inferred from bodies and other files), or null
  * when the compiler has no `transpileDeclaration` (before TypeScript 5.5). A declaration whose only diagnostics are components returning JSX has the

package/runtime/scripts/lib/declaration-surface.mjs

@@ -55,6 +55,52 @@ function returnsOnlyJsx(ts, source, start) {
     ts.forEachChild(fn.body, visit);
     return only;
 }
+/** The package whose module-definition helpers return a type they state in their own declaration (R368 accepts a destructured export of their call). */
+export const STATED_SURFACE_PACKAGE = '@starci/nest-kit';
+/** The helpers of that package: each is called with the options type as a type argument and returns the explicitly typed definition. */
+export const STATED_SURFACE_HELPERS = new Set(['defineConfigurableModule', 'defineCapabilityModule']);
+/** The local names under which `source` imports a stated-surface helper from its package (`import { defineConfigurableModule as define }` gives `define`). */
+function statedHelperNames(ts, source) {
+    const names = new Set();
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== STATED_SURFACE_PACKAGE)
+            continue;
+        const bindings = statement.importClause?.namedBindings;
+        if (bindings === undefined || !ts.isNamedImports(bindings))
+            continue;
+        for (const element of bindings.elements)
+            if (STATED_SURFACE_HELPERS.has((element.propertyName ?? element.name).text))
+                names.add(element.name.text);
+    }
+    return names;
+}
+/**
+ * Whether the destructured export the diagnostic at `start` points at is `export const { A, B } = helper<Options>()` for a stated-surface helper:
+ * each name has the type the helper's declaration gives it, written there, so the file states its surface by naming the helper and the options
+ * type, exactly as `export const A: Host["A"] = built.A` states it through `Host`.
+ */
+function statesSurfaceThroughHelper(ts, source, start) {
+    const helpers = statedHelperNames(ts, source);
+    if (helpers.size === 0)
+        return null;
+    let innermost = source;
+    const descend = (node) => {
+        if (start < node.getFullStart() || start >= node.end)
+            return;
+        innermost = node;
+        ts.forEachChild(node, descend);
+    };
+    ts.forEachChild(source, descend);
+    for (let node = innermost; node !== undefined && node !== source; node = node.parent) {
+        if (!ts.isVariableDeclaration(node))
+            continue;
+        const call = node.initializer;
+        const stated = ts.isObjectBindingPattern(node.name) && call !== undefined && ts.isCallExpression(call) && ts.isIdentifier(call.expression) && helpers.has(call.expression.text)
+            && (call.typeArguments?.length ?? 0) > 0 && node.name.elements.every((element) => ts.isIdentifier(element.name) && element.dotDotDotToken === undefined);
+        return stated && call !== undefined ? call.getText(source) : null;
+    }
+    return null;
+}
 /** What to annotate for each isolated-declaration diagnostic code; any other code asks for the exported value's type. */
 const ANNOTATE = new Map([
     [9007, 'return type'], [9008, 'return type'], [9009, 'accessor type'], [9010, 'variable type'], [9011, 'parameter type'], [9012, 'property type'],
@@ -98,7 +144,14 @@ export function declarationSurface(ts, file, text, module) {
         return { outputText: declared.outputText, problems: [] };
     const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
     const problems = [];
+    // The emit writes `any` for a destructured export; the call that states its type joins the digest, so a change of the options type reaches the importers.
+    const stated = new Set();
     for (const diagnostic of diagnostics) {
+        const call = diagnostic.code === 9019 && diagnostic.start !== undefined ? statesSurfaceThroughHelper(ts, source, diagnostic.start) : null;
+        if (call !== null) {
+            stated.add(call);
+            continue;
+        }
         const exempt = (diagnostic.code === 9007 || diagnostic.code === 9008) && diagnostic.start !== undefined && returnsOnlyJsx(ts, source, diagnostic.start);
         if (exempt)
             continue;
@@ -108,5 +161,6 @@ export function declarationSurface(ts, file, text, module) {
             reason: ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n').split('\n')[0] ?? '',
         });
     }
-    return { outputText: declared.outputText, problems };
+    const outputText = stated.size === 0 ? declared.outputText : `${declared.outputText}${[...stated].sort().map((call) => `// stated by ${call}\n`).join('')}`;
+    return { outputText, problems };
 }