@caelo-cms/provisioning 0.10.53 → 0.10.55

package/src/caddy.test.ts

@@ -3,6 +3,7 @@
 import { describe, expect, it } from "bun:test";
 import {
   type CaddyfileSpec,
+  caddyTokenProblem,
   generateCaddyfile,
   selfHostedAdminHost,
   selfHostedSeedDomains,
@@ -105,4 +106,33 @@ describe("Caddyfile TLS", () => {
     const out = generateCaddyfile({ ...spec, tls: "internal" });
     expect(out.startsWith("{\n  email owner@example.com\n  local_certs\n}\n")).toBe(true);
   });
+
+  it("rejects unsafe characters in ownerEmail and domain hostnames", () => {
+    expect(() => generateCaddyfile({ ...spec, ownerEmail: "owner@example.com\n  debug" })).toThrow(
+      /invalid ownerEmail/,
+    );
+    expect(() =>
+      generateCaddyfile({
+        ...spec,
+        domains: [
+          { hostname: "evil.example.com {\n  respond 200\n}", kind: "public", env: "production" },
+        ],
+      }),
+    ).toThrow(/invalid hostname/);
+  });
+
+  it("refuses a comma in a site address — it would add a second address to the block", () => {
+    // `admin.example.com,:80` would serve the admin on every host on port 80.
+    expect(() =>
+      generateCaddyfile({
+        ...spec,
+        domains: [{ hostname: "admin.example.com,:80", kind: "admin", env: "production" }],
+      }),
+    ).toThrow(/invalid hostname/);
+    // A comma is harmless inside a token like the email.
+    expect(caddyTokenProblem("a,b@example.com", "token")).toBeNull();
+    expect(caddyTokenProblem("a,b.example.com", "address")).toMatch(/','/);
+    expect(caddyTokenProblem("", "token")).toBe("it is empty");
+    expect(caddyTokenProblem("192.168.1.10", "address")).toBeNull();
+  });
 });

package/src/caddy.ts

@@ -103,9 +103,52 @@ export function selfHostedSeedDomains(domain: string, stagingDomain: string): Ca
   ];
 }
 
+/**
+ * Characters that would let a value end its Caddyfile token and start new
+ * directives or blocks: whitespace (incl. newlines), both quote styles Caddy
+ * tokenizes (`"` and backtick), braces (blocks and `{placeholders}`), the
+ * comment marker, escapes and semicolons. A site address additionally may
+ * not hold a comma, which would add further addresses to the same block.
+ */
+const UNSAFE_CADDY_TOKEN_RE = /[\s"`{}#\\;]/;
+const UNSAFE_CADDY_ADDRESS_RE = /[\s"`{}#\\;,]/;
+
+/**
+ * Why `value` cannot go into the Caddyfile as one token, or null when it can.
+ * `init` checks the operator's domains and email with this before it writes
+ * anything, so a bad value never leaves a half-made install behind.
+ *
+ * @param kind `address` for a site address (hostname), `token` for any other value
+ */
+export function caddyTokenProblem(value: string, kind: "address" | "token"): string | null {
+  if (value.length === 0) return "it is empty";
+  const unsafe = kind === "address" ? UNSAFE_CADDY_ADDRESS_RE : UNSAFE_CADDY_TOKEN_RE;
+  if (unsafe.test(value)) {
+    return `it contains whitespace, a quote, a brace, '#', '\\', ';'${kind === "address" ? " or ','" : ""}`;
+  }
+  return null;
+}
+
+function assertSafeCaddyToken(label: string, value: string, kind: "address" | "token"): void {
+  const problem = caddyTokenProblem(value, kind);
+  if (problem) {
+    throw new Error(
+      `Caddyfile: invalid ${label} ${JSON.stringify(value)} — ${problem}. Fix the value in .caelo/config.json (or the domain you added) and run the command again.`,
+    );
+  }
+}
+
+/** Every caller-supplied value is checked before any of it is emitted (#888). */
 export function generateCaddyfile(spec: CaddyfileSpec): string {
+  assertSafeCaddyToken("ownerEmail", spec.ownerEmail, "token");
+  assertSafeCaddyToken("publicSiteRoot", spec.publicSiteRoot, "token");
+  assertSafeCaddyToken("stagingSiteRoot", spec.stagingSiteRoot, "token");
+  assertSafeCaddyToken("adminUpstream", spec.adminUpstream, "token");
+  assertSafeCaddyToken("gatewayUpstream", spec.gatewayUpstream, "token");
+
   const hostnames = new Set<string>();
   for (const d of spec.domains) {
+    assertSafeCaddyToken("hostname", d.hostname, "address");
     if (hostnames.has(d.hostname)) {
       // Caddy refuses a config with two site blocks for one address, so a
       // duplicate would take every vhost down, not just this one.

package/src/cli-init-validation.test.ts

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: MPL-2.0
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+const CLI = resolve(import.meta.dir, "cli.ts");
+
+let dir: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "caelo-init-validation-"));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+function init(...args: string[]) {
+  return Bun.spawnSync([process.execPath, CLI, "init", ...args], {
+    env: { ...process.env, CAELO_SELF_HOSTED_DIR: join(dir, ".caelo") },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+}
+
+describe("cms-provision init refuses a value the Caddyfile cannot hold before writing anything", () => {
+  // Checked only when the Caddyfile was generated, a bad value left
+  // config.json behind, and the re-run stopped at "config already exists".
+  for (const [flag, value] of [
+    ["--domain", "example.com,:80"],
+    ["--domain", "example.com {\n  respond 200\n}"],
+    ["--owner-email", "owner@example.com\n  debug"],
+    ["--staging-domain", "staging.example.com #"],
+  ] as const) {
+    it(`${flag} ${JSON.stringify(value)}`, () => {
+      const base: Record<string, string> = {
+        "--domain": "example.com",
+        "--owner-email": "owner@example.com",
+      };
+      base[flag] = value;
+      const r = init(...Object.entries(base).flat());
+      expect(r.exitCode).toBe(2);
+      expect(r.stderr.toString()).toContain(flag);
+      expect(existsSync(join(dir, ".caelo"))).toBe(false);
+    });
+  }
+});

package/src/cli.ts

@@ -51,6 +51,7 @@ import { generateBootstrapToken } from "./bootstrap-token.js";
 import {
   type CaddyDomainSpec,
   type CaddyTlsMode,
+  caddyTokenProblem,
   generateCaddyfile,
   selfHostedAdminHost,
   selfHostedSeedDomains,
@@ -71,6 +72,7 @@ import {
   SITE_OUTPUT_ROOT,
   selfHostedSiteUrl,
 } from "./compose.js";
+import { tightenPrivateTree, writePrivateFile } from "./private-file.js";
 import { selfCommand } from "./self-command.js";
 import {
   bunHostRunner,
@@ -192,8 +194,8 @@ function loadProvider(): Provider {
 }
 
 function saveProvider(provider: Provider): void {
-  if (!existsSync(CAELO_DIR)) mkdirSync(CAELO_DIR, { recursive: true });
-  writeFileSync(PROVIDER_PATH, JSON.stringify({ provider }, null, 2));
+  if (!existsSync(CAELO_DIR)) mkdirSync(CAELO_DIR, { recursive: true, mode: 0o700 });
+  writePrivateFile(PROVIDER_PATH, JSON.stringify({ provider }, null, 2));
 }
 
 /**
@@ -224,6 +226,20 @@ function randomSecret(bytes = 32): string {
 
 function loadConfig(): CaeloConfig | null {
   if (!existsSync(CONFIG_PATH)) return null;
+  // Every command that works on an install reads its config first, so this
+  // is where an install made by an older CLI loses its world-readable
+  // secrets (#888) — not only once each file happens to be rewritten.
+  tightenPrivateTree(
+    CAELO_DIR,
+    [BOOTSTRAP_DIR, "backups"],
+    [
+      "config.json",
+      "provider.json",
+      "internal-secret.json",
+      "docker-compose.yml",
+      `${BOOTSTRAP_DIR}/pending-token.json`,
+    ],
+  );
   const cfg = JSON.parse(readFileSync(CONFIG_PATH, "utf8")) as CaeloConfig;
   // #707 — settings added later, back-filled (and stored) with what every
   // install ran before they existed, so `upgrade` / `agent` render the same
@@ -238,8 +254,8 @@ function loadConfig(): CaeloConfig | null {
 }
 
 function saveConfig(c: CaeloConfig): void {
-  if (!existsSync(CAELO_DIR)) mkdirSync(CAELO_DIR, { recursive: true });
-  writeFileSync(CONFIG_PATH, JSON.stringify(c, null, 2));
+  if (!existsSync(CAELO_DIR)) mkdirSync(CAELO_DIR, { recursive: true, mode: 0o700 });
+  writePrivateFile(CONFIG_PATH, JSON.stringify(c, null, 2));
 }
 
 function arg(name: string): string | undefined {
@@ -293,7 +309,7 @@ function emitConfig(cfg: CaeloConfig, extraDomains: CaddyDomainSpec[] = []): voi
  * operator-added domains only `up` / `regenerate-caddy` read back).
  */
 function emitComposeFiles(cfg: CaeloConfig): void {
-  writeFileSync(COMPOSE_PATH, renderCompose(cfg, installImages(cfg)), { mode: 0o600 });
+  writePrivateFile(COMPOSE_PATH, renderCompose(cfg, installImages(cfg)));
   // No secrets (it reads the passwords from the container's environment),
   // and the postgres user inside the container must be able to read it.
   writeFileSync(
@@ -527,6 +543,19 @@ async function init(): Promise<void> {
     console.error(`--staging-domain: ${stagingProblem}`);
     process.exit(2);
   }
+  // The Caddyfile check would only fire in emitConfig, after config.json is
+  // written — and a re-run then stops at "config already exists".
+  for (const [flag, value, kind] of [
+    ["--domain", domain, "address"],
+    ["--staging-domain", stagingArg, "address"],
+    ["--owner-email", ownerEmail, "token"],
+  ] as const) {
+    const problem = value === undefined ? null : caddyTokenProblem(value, kind);
+    if (problem) {
+      console.error(`${flag} ${JSON.stringify(value)}: ${problem}.`);
+      process.exit(2);
+    }
+  }
   // #696 — the prebuilt release images, resolved to digests and
   // cosign-verified BEFORE anything is written, so a failed check leaves no
   // half-made install. `--dev` (contributors only) runs this checkout instead.
@@ -589,7 +618,7 @@ async function init(): Promise<void> {
   // staging file.
   const tok = generateBootstrapToken();
   mkdirSync(resolve(CAELO_DIR, BOOTSTRAP_DIR), { recursive: true, mode: 0o700 });
-  writeFileSync(PENDING_TOKEN_PATH, JSON.stringify(tok, null, 2), { mode: 0o600 });
+  writePrivateFile(PENDING_TOKEN_PATH, JSON.stringify(tok, null, 2));
 
   // P15.1 — mint the shared HMAC secret for /api/internal/* endpoints.
   // Same secret is read by:
@@ -601,7 +630,7 @@ async function init(): Promise<void> {
   // internal-secret`.
   const internalSecret = randomSecret(48);
   const internalSecretPath = resolve(CAELO_DIR, "internal-secret.json");
-  writeFileSync(internalSecretPath, JSON.stringify({ secret: internalSecret }, null, 2));
+  writePrivateFile(internalSecretPath, JSON.stringify({ secret: internalSecret }, null, 2));
   // #696 Phase 4c — the update agent (Linux + systemd): the fresh volume's
   // bootstrap.sh creates its database login on Postgres's first start.
   const { reportAgentSetup, setUpAgent } = await import("./agent/command.js");

package/src/gcp-names.ts

@@ -69,7 +69,7 @@ export function staticPublisherServiceAccountId(env: string): string {
 export function gcpBucketName(
   projectId: string,
   env: string,
-  bucket: "media" | "static" | "staging",
+  bucket: "media" | "static" | "staging" | "audit-results",
 ): string {
   return `${projectId}-${gcpNamePrefix(env)}-${bucket}`;
 }
@@ -120,6 +120,33 @@ export function upgraderJobResource(projectId: string, region: string, env: stri
   return `projects/${projectId}/locations/${region}/jobs/${upgraderJobName(env)}`;
 }
 
+/**
+ * #875 — Cloud Run job that runs the quality audit's Lighthouse runs in
+ * parallel, one task per run (audit-job-setup.ts).
+ */
+export function auditJobName(env: string): string {
+  return `${gcpNamePrefix(env)}-audit`;
+}
+
+/** Full resource name of the audit job, as the admin's env carries it. */
+export function auditJobResource(projectId: string, region: string, env: string): string {
+  return `projects/${projectId}/locations/${region}/jobs/${auditJobName(env)}`;
+}
+
+/**
+ * Account id of the audit job's own service account: reads the staged
+ * build, creates audit results, writes logs — nothing else
+ * (audit-job-setup.ts).
+ */
+export function auditServiceAccountId(env: string): string {
+  return `${gcpNamePrefix(env)}-audit`;
+}
+
+/** Email of the audit job's service account. */
+export function auditServiceAccountEmail(projectId: string, env: string): string {
+  return `${auditServiceAccountId(env)}@${projectId}.iam.gserviceaccount.com`;
+}
+
 /**
  * Account id of the upgrader job's own service account: may roll the two
  * Cloud Run services, run the migration job and back up Cloud SQL, never

package/src/infra-contract.test.ts

@@ -20,8 +20,8 @@ describe("infrastructure contract steps", () => {
     );
   });
 
-  it("is at 7: public_role revoke (3), URL-map redirects role (4), no gateway cms_admin login (5), ops-bucket list (6), gateway proxy hops (7)", () => {
-    expect(INFRA_CONTRACT_VERSION).toBe(7);
+  it("is at 8: public_role revoke (3), URL-map redirects role (4), no gateway cms_admin login (5), ops-bucket list (6), gateway proxy hops (7), quality-audit job (8)", () => {
+    expect(INFRA_CONTRACT_VERSION).toBe(8);
     expect(INFRA_CONTRACT_STEPS[3]).toContain("#633");
     expect(INFRA_CONTRACT_STEPS[4]).toContain("#587");
     expect(INFRA_CONTRACT_STEPS[5]).toContain("#635");
@@ -37,6 +37,6 @@ describe("infrastructure contract steps", () => {
   });
 
   it("names a version a newer release added by number", () => {
-    expect(infraStepsText(7, 8)).toBe("infrastructure step 8 (see that release's notes)");
+    expect(infraStepsText(8, 9)).toBe("infrastructure step 9 (see that release's notes)");
   });
 });

package/src/infra-contract.ts

@@ -22,7 +22,7 @@
  * whose app-roll references infrastructure an install does not have yet fails
  * at roll time, after migrations ran.
  */
-export const INFRA_CONTRACT_VERSION = 7;
+export const INFRA_CONTRACT_VERSION = 8;
 
 // History (why each bump happened — an install below a number needs the
 // converge that introduced it):
@@ -51,6 +51,11 @@ export const INFRA_CONTRACT_VERSION = 7;
 //       runs from (the installed one), which does not set it — so the new
 //       gateway would not start. The operator-identity upgrade runs the new
 //       release's contract and sets it.
+//   8 — #875: the quality-audit job, its service account, the audit results
+//       bucket and their grants, plus CAELO_AUDIT_JOB /
+//       CAELO_AUDIT_RESULTS_BUCKET on the admin. The new admin fans every
+//       Stage audit out to that job, and the app-roll moves the job's image,
+//       so it must exist before an in-cloud upgrader rolls onto it.
 
 /**
  * What each contract version adds, in operator terms — the upgrader's
@@ -65,6 +70,7 @@ export const INFRA_CONTRACT_STEPS: Readonly<Record<number, string>> = {
   5: "the gateway's cms_admin login removed from its env and IAM (#635)",
   6: "the upgrader's permission to list its ops bucket (#799)",
   7: "the gateway's trusted proxy hop count, CAELO_TRUSTED_PROXY_HOPS (#845)",
+  8: "the quality-audit job, its service account, results bucket and grants (#875)",
 };
 
 /**

package/src/private-file.test.ts

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: MPL-2.0
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import {
+  chmodSync,
+  closeSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { tightenPrivateTree, writePrivateFile } from "./private-file.js";
+
+let dir: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "caelo-private-file-"));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+const mode = (path: string) => statSync(path).mode & 0o777;
+
+describe("writePrivateFile", () => {
+  it("creates the file owner-only and replaces a world-readable file with an owner-only one", () => {
+    const fresh = join(dir, "fresh.json");
+    writePrivateFile(fresh, "{}");
+    expect(mode(fresh)).toBe(0o600);
+
+    const legacy = join(dir, "legacy.json");
+    writeFileSync(legacy, "{}", { mode: 0o644 });
+    chmodSync(legacy, 0o644);
+    writePrivateFile(legacy, '{"secret":"x"}');
+    expect(mode(legacy)).toBe(0o600);
+    expect(readFileSync(legacy, "utf8")).toBe('{"secret":"x"}');
+    expect(readdirSync(dir).sort()).toEqual(["fresh.json", "legacy.json"]);
+  });
+
+  it("never writes the new secret into the old world-readable inode", () => {
+    // A local user who opened the 0644 file before the rewrite keeps that
+    // descriptor; a write-then-chmod would let it read the new secret.
+    const legacy = join(dir, "internal-secret.json");
+    writeFileSync(legacy, "old");
+    chmodSync(legacy, 0o644);
+    const fd = openSync(legacy, "r");
+    try {
+      writePrivateFile(legacy, "new-secret");
+      const buf = Buffer.alloc(64);
+      const n = readSync(fd, buf, 0, buf.length, 0);
+      expect(buf.subarray(0, n).toString()).toBe("old");
+    } finally {
+      closeSync(fd);
+    }
+  });
+});
+
+describe("tightenPrivateTree", () => {
+  it("takes group/other access off an older install's directory and secrets, skipping missing ones", () => {
+    const install = join(dir, ".caelo");
+    mkdirSync(join(install, "bootstrap"), { recursive: true });
+    chmodSync(install, 0o755);
+    chmodSync(join(install, "bootstrap"), 0o755);
+    writeFileSync(join(install, "config.json"), "{}");
+    chmodSync(join(install, "config.json"), 0o644);
+    writeFileSync(join(install, "Caddyfile"), "");
+    chmodSync(join(install, "Caddyfile"), 0o644);
+
+    tightenPrivateTree(install, ["bootstrap", "backups"], ["config.json", "internal-secret.json"]);
+
+    expect(mode(install)).toBe(0o700);
+    expect(mode(join(install, "bootstrap"))).toBe(0o700);
+    expect(mode(join(install, "config.json"))).toBe(0o600);
+    // Not a secret: the Caddy container reads it through its bind mount.
+    expect(mode(join(install, "Caddyfile"))).toBe(0o644);
+  });
+});

package/src/private-file.ts

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: MPL-2.0
+import { randomUUID } from "node:crypto";
+import { chmodSync, existsSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+
+/**
+ * Write a file only its owner may read (0600), replacing any file at `path`.
+ *
+ * The data goes into a fresh temp file created 0600 (`wx`, so never an
+ * existing file or a planted symlink) and is renamed over `path`. Writing in
+ * place would not do: `writeFileSync`'s `mode` applies only when the call
+ * creates the file, so a secret file an older CLI wrote world-readable would
+ * hold the new secret world-readable until a chmod after the write — and a
+ * reader that opened it before any chmod keeps its descriptor. The rename
+ * gives the new contents a new inode that was never readable by anyone else.
+ */
+export function writePrivateFile(path: string, data: string): void {
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, data, { mode: 0o600, flag: "wx" });
+  try {
+    renameSync(tmp, path);
+  } catch (e) {
+    rmSync(tmp, { force: true });
+    throw e;
+  }
+}
+
+/**
+ * Take group/other access off an install's secrets directory and the secret
+ * files in it, for installs an older CLI created with the default umask
+ * (`.caelo/` 0755, `config.json` / `internal-secret.json` 0644). Those files
+ * are written once and rarely rewritten, so tightening only on the next write
+ * would leave them readable to every local user. Missing paths are skipped:
+ * which secrets exist depends on the provider and how far `init` got.
+ *
+ * @param dir the install's directory, tightened to 0700
+ * @param privateDirs subdirectories (relative to `dir`) tightened to 0700
+ * @param privateFiles files (relative to `dir`) tightened to 0600
+ */
+export function tightenPrivateTree(
+  dir: string,
+  privateDirs: readonly string[],
+  privateFiles: readonly string[],
+): void {
+  const tighten = (path: string, mode: number) => {
+    if (existsSync(path) && (statSync(path).mode & 0o077) !== 0) chmodSync(path, mode);
+  };
+  tighten(dir, 0o700);
+  for (const sub of privateDirs) tighten(`${dir}/${sub}`, 0o700);
+  for (const file of privateFiles) tighten(`${dir}/${file}`, 0o600);
+}

package/src/release-contract.ts

@@ -49,6 +49,9 @@ export const INFRA_CONTRACT_PATHS: readonly string[] = [
   // The in-cloud upgrader job's service account, custom roles and bucket
   // grants (#799 added one without the checks noticing).
   "packages/provisioning/src/upgrader-setup.ts",
+  // #875 — the quality-audit job, its service account, results bucket and
+  // grants.
+  "packages/provisioning/src/audit-job-setup.ts",
 ];
 
 /**

package/src/stack-contract.test.ts

@@ -74,6 +74,8 @@ describe("adminEnvContract", () => {
       CAELO_OPERATOR_ACCESS_JOB:
         "projects/acme/locations/europe-west1/jobs/caelo-production-operator-access-sync",
       CAELO_UPGRADER_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-upgrader",
+      CAELO_AUDIT_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-audit",
+      CAELO_AUDIT_RESULTS_BUCKET: "acme-caelo-production-audit-results",
       CAELO_STATIC_BUCKET: "acme-caelo-production-static",
       CAELO_STAGING_BUCKET: "acme-caelo-production-staging",
       ...ADMIN_SECRETS,
@@ -104,6 +106,8 @@ describe("adminEnvContract", () => {
       CAELO_OPERATOR_ACCESS_JOB:
         "projects/acme/locations/europe-west1/jobs/caelo-production-operator-access-sync",
       CAELO_UPGRADER_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-upgrader",
+      CAELO_AUDIT_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-audit",
+      CAELO_AUDIT_RESULTS_BUCKET: "acme-caelo-production-audit-results",
       CAELO_FIREBASE_SITE: "caelo-production-site-abc123",
       CAELO_GATEWAY_SERVICE: "caelo-production-gateway-1a2b3c4",
       CAELO_GATEWAY_REGION: "europe-west1",

package/src/stack-contract.ts

@@ -36,6 +36,7 @@
 
 import type { SupportedProvider } from "./adapter.js";
 import {
+  auditJobResource,
   gatewayServiceAccountEmail,
   gcpBucketName,
   gcpNamePrefix,
@@ -169,6 +170,15 @@ export const OPERATOR_ACCESS_JOB_ENV_VAR = "CAELO_OPERATOR_ACCESS_JOB";
  */
 export const UPGRADER_JOB_ENV_VAR = "CAELO_UPGRADER_JOB";
 
+/**
+ * #875 — the admin env vars naming the parallel quality-audit job and the
+ * bucket its tasks write results into (admin-core quality/
+ * gcp-audit-launcher.ts). `upgrade` leaves them untouched when it could not
+ * set the job up.
+ */
+export const AUDIT_JOB_ENV_VAR = "CAELO_AUDIT_JOB";
+export const AUDIT_RESULTS_BUCKET_ENV_VAR = "CAELO_AUDIT_RESULTS_BUCKET";
+
 /** Where the admin image ships the static-generator CLI. */
 const GENERATOR_CLI = "/app/apps/static-generator/src/cli.ts";
 
@@ -442,6 +452,10 @@ export function adminEnvContract<V>(inputs: AdminEnvInputs<V>): CloudRunEnvVar<V
     // #696 — the job "Install update" starts (upgrader-setup.ts); the admin
     // may only run it, never override it.
     { name: UPGRADER_JOB_ENV_VAR, value: upgraderJobResource(projectId, inputs.region, env) },
+    // #875 — the job the quality audit fans its Lighthouse runs out to, and
+    // where the tasks write their results (audit-job-setup.ts).
+    { name: AUDIT_JOB_ENV_VAR, value: auditJobResource(projectId, inputs.region, env) },
+    { name: AUDIT_RESULTS_BUCKET_ENV_VAR, value: gcpBucketName(projectId, env, "audit-results") },
   ];
   if (inputs.provider === "gcp") {
     // v0.2.78 — the GCS StaticPublisher: Stage uploads to staging,

package/src/stack-converge.test.ts

@@ -312,7 +312,7 @@ describe("planContractEnv", () => {
     // #650 — the same roll converges the protected staging domain's host
     // and gate key onto an install that predates it.
     expect(plan.services.admin.flags).toEqual([
-      "--update-env-vars=CAELO_SITE_URL=https://acme.com,MEDIA_ROOT_DIR=/app/apps/admin/data/media,CAELO_MCP_IAP_SERVICE_ACCOUNT=caelo-mcp@acme.iam.gserviceaccount.com,CAELO_OPERATOR_ACCESS_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-operator-access-sync,CAELO_UPGRADER_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-upgrader,CAELO_STAGING_HOST=staging.acme.com",
+      "--update-env-vars=CAELO_SITE_URL=https://acme.com,MEDIA_ROOT_DIR=/app/apps/admin/data/media,CAELO_MCP_IAP_SERVICE_ACCOUNT=caelo-mcp@acme.iam.gserviceaccount.com,CAELO_OPERATOR_ACCESS_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-operator-access-sync,CAELO_UPGRADER_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-upgrader,CAELO_AUDIT_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-audit,CAELO_AUDIT_RESULTS_BUCKET=acme-caelo-production-audit-results,CAELO_STAGING_HOST=staging.acme.com",
       "--update-secrets=CAELO_STAGING_GATE_SECRET=caelo-production-staging-gate-secret:latest",
     ]);
     expect(plan.services.gateway.flags).toEqual([