diff --git a/scripts/saleable-readiness-audit.mjs b/scripts/saleable-readiness-audit.mjs index 0054030f6..680f07e20 100644 --- a/scripts/saleable-readiness-audit.mjs +++ b/scripts/saleable-readiness-audit.mjs @@ -41,6 +41,16 @@ const readinessSubprocessEnvironmentKeys = Object.freeze([ "NOEMA_AUDIT_REPORT_ONLY", ]); +/** + * Build the least-authority environment for saleable-readiness child commands. + * + * Explicit call-site overrides take precedence over the reviewed ambient + * runtime allowlist. Unrelated credentials, proxy state, and process hooks are + * intentionally excluded from child authority. + * + * @param {Record} overrides reviewed per-command environment overrides + * @returns {Record} bounded child-process environment + */ function createReadinessSubprocessEnvironment(overrides = {}) { const env = {}; for (const key of readinessSubprocessEnvironmentKeys) { diff --git a/test/saleable-readiness-subprocess-environment.test.ts b/test/saleable-readiness-subprocess-environment.test.ts index 0bc3cfdc9..4f893db30 100644 --- a/test/saleable-readiness-subprocess-environment.test.ts +++ b/test/saleable-readiness-subprocess-environment.test.ts @@ -52,4 +52,17 @@ describe("saleable readiness subprocess authority", () => { expect(script).not.toContain(`\"${forbiddenAmbientAuthority}\"`); } }); + + it("documents the least-authority child environment contract beside its implementation", () => { + const script = readFileSync("scripts/saleable-readiness-audit.mjs", "utf8"); + const signature = "function createReadinessSubprocessEnvironment(overrides = {})"; + const signatureIndex = script.indexOf(signature); + + expect(signatureIndex).toBeGreaterThanOrEqual(0); + const jsdoc = script.slice(0, signatureIndex).match(/\/\*\*[\s\S]*?\*\/\s*$/)?.[0]; + expect(jsdoc).toBeDefined(); + expect(jsdoc).toContain("least-authority"); + expect(jsdoc).toContain("@param"); + expect(jsdoc).toContain("@returns"); + }); });