@caelo-cms/provisioning 0.10.60 → 0.10.62

package/src/state-pulumi.ts

@@ -3,7 +3,8 @@
 /**
  * The real {@link StatePulumiOps} for `state migrate` (#696): the Pulumi CLI
  * (state operations) and the Automation API (previews), always in the
- * install's stack dir and with exactly the backend's environment. The
+ * install's own stack work dir (#736) and with exactly the backend's
+ * environment. The
  * operator never runs `pulumi` by hand (CLAUDE.md §11.C).
  *
  * Secrets: outputs are read with `--show-secrets` only to hash them; the
@@ -18,12 +19,14 @@ import { join } from "node:path";
 import * as automation from "@pulumi/pulumi/automation";
 import { redactCredentials } from "./checkpoint-secrets.js";
 import { GCP_STACK_ENV } from "./gcp-names.js";
+import { collectPreviewSteps } from "./preview-plan.js";
 import type { ResolvedBackend } from "./state-backend.js";
 import type { StatePulumiOps } from "./state-migrate.js";
 import {
   alignStackSettingsFile,
   applyStackConfig,
-  gcpStackWorkDir,
+  assertStackProject,
+  prepareStackWorkDir,
   pulumiGcpEnv,
   type StackConfigInputs,
   type StateResource,
@@ -49,13 +52,6 @@ export function canonicalJson(value: unknown): string {
   return JSON.stringify(value);
 }
 
-/** Steps of a preview's change summary other than "same". */
-export function changeCount(summary: Readonly<Record<string, number | undefined>>): number {
-  return Object.entries(summary)
-    .filter(([op]) => op !== "same")
-    .reduce((n, [, c]) => n + (c ?? 0), 0);
-}
-
 interface Deployment {
   pending_operations?: unknown[];
   secrets_providers?: {
@@ -76,7 +72,7 @@ export interface RealPulumiOpsInputs {
 
 /** {@link StatePulumiOps} backed by the `pulumi` CLI + Automation API. */
 export function realStatePulumiOps(inputs: RealPulumiOpsInputs): StatePulumiOps {
-  const workDir = gcpStackWorkDir(inputs.provider);
+  const workDir = prepareStackWorkDir(inputs.installRoot, inputs.provider);
 
   const cli = async (
     args: string[],
@@ -99,7 +95,7 @@ export function realStatePulumiOps(inputs: RealPulumiOpsInputs): StatePulumiOps
     return { stdout, stderr };
   };
 
-  // The read-only steps (preflight, verification) align the package's
+  // The read-only steps (preflight, verification) align the install's
   // stack settings file and may set config to run a preview; the file is
   // put back exactly as it was afterwards, so a refused migration or a dry
   // run leaves it untouched.
@@ -127,7 +123,7 @@ export function realStatePulumiOps(inputs: RealPulumiOpsInputs): StatePulumiOps
   };
 
   const exportDeployment = async (b: ResolvedBackend): Promise<Deployment> => {
-    await alignStackSettingsFile(b, inputs.provider);
+    await alignStackSettingsFile(workDir, b);
     const { stdout } = await cli(["stack", "export", "--stack", GCP_STACK_ENV], stateOnlyEnv(b));
     return ((JSON.parse(stdout) as { deployment?: Deployment }).deployment ?? {}) as Deployment;
   };
@@ -179,7 +175,7 @@ export function realStatePulumiOps(inputs: RealPulumiOpsInputs): StatePulumiOps
     },
 
     async previewChanges(b) {
-      await alignStackSettingsFile(b, inputs.provider);
+      await alignStackSettingsFile(workDir, b);
       const stack = await automation.LocalWorkspace.selectStack(
         { stackName: GCP_STACK_ENV, workDir },
         {
@@ -191,21 +187,24 @@ export function realStatePulumiOps(inputs: RealPulumiOpsInputs): StatePulumiOps
       );
       // The stack's own config wins: an operator may have tuned a knob
       // (`pulumi config set`), and resetting it would show as drift. Only a
-      // stack dir without the install's config (a fresh `bunx` version)
-      // gets what the wizard sets — as does one holding another install's
-      // config (installs of one provider share the package's stack dir).
+      // settings file without the install's config (an install from before
+      // its own work dir, #736) gets what the wizard sets.
       const config: automation.ConfigMap = await stack.getAllConfig().catch(() => ({}));
-      if (config[`caelo-${inputs.provider}:project`]?.value !== inputs.stackConfig.projectId) {
+      if (config[`caelo-${inputs.provider}:project`] === undefined) {
         const resources = ((await stack.exportStack()).deployment?.resources ??
           []) as StateResource[];
         await applyStackConfig(stack, inputs.stackConfig, resources);
       }
-      const r = await stack.preview({ refresh: true });
-      return changeCount(r.changeSummary);
+      await assertStackProject(stack, inputs.provider, inputs.stackConfig.projectId);
+      // #737 — the steps themselves, not just the summary's count: a
+      // refusal lists what would change, replaces and deletes first.
+      const collector = collectPreviewSteps();
+      await stack.preview({ refresh: true, onEvent: collector.onEvent });
+      return collector.steps();
     },
 
     async outputsDigest(b) {
-      await alignStackSettingsFile(b, inputs.provider);
+      await alignStackSettingsFile(workDir, b);
       const { stdout } = await cli(
         ["stack", "output", "--stack", GCP_STACK_ENV, "--json", "--show-secrets"],
         stateOnlyEnv(b),
@@ -216,7 +215,7 @@ export function realStatePulumiOps(inputs: RealPulumiOpsInputs): StatePulumiOps
     },
 
     async stackMigrate(from, to) {
-      await alignStackSettingsFile(from, inputs.provider);
+      await alignStackSettingsFile(workDir, from);
       await cli(
         [
           "stack",

package/src/static-security-headers.test.ts

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #891 regression: the public static site served user-uploaded SVGs from
+ * the CDN with no CSP on every provider, so a script that got past
+ * `sanitizeSvg` ran on the site's origin (the one that also serves
+ * `/api/*`) when the SVG's URL was opened. These tests pin each provider's
+ * edge config and that every stack wires it (source-level for the stacks:
+ * the Pulumi programs cannot run in a unit test).
+ */
+
+import { describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { NOSNIFF, SVG_DOCUMENT_CSP } from "@caelo-cms/shared";
+import {
+  CLOUDFRONT_SVG_BEHAVIORS,
+  cloudFrontHeadersPolicy,
+  FRONT_DOOR_SECURITY_RULE_SET,
+  frontDoorSecurityRules,
+  GCP_STATIC_RESPONSE_HEADERS,
+} from "./static-security-headers.js";
+
+const stack = (provider: string): string =>
+  readFileSync(resolve(import.meta.dir, "..", "stacks", provider, "index.ts"), "utf8");
+
+describe("AWS CloudFront response headers policies", () => {
+  it("site: nosniff only (a CSP with sandbox would break every page)", () => {
+    const p = cloudFrontHeadersPolicy("site");
+    expect(p.securityHeadersConfig.contentTypeOptions).toEqual({ override: true });
+    expect(p.securityHeadersConfig.contentSecurityPolicy).toBeUndefined();
+  });
+
+  it("svg: nosniff + the sandboxing CSP, overriding any origin header", () => {
+    const p = cloudFrontHeadersPolicy("svg");
+    expect(p.securityHeadersConfig.contentTypeOptions).toEqual({ override: true });
+    expect(p.securityHeadersConfig.contentSecurityPolicy).toEqual({
+      contentSecurityPolicy: SVG_DOCUMENT_CSP,
+      override: true,
+    });
+  });
+
+  it("SVG behaviors cover both S3 origins, the media one first (first match wins)", () => {
+    expect(CLOUDFRONT_SVG_BEHAVIORS).toEqual([
+      { pathPattern: "/media/*.svg", targetOriginId: "media" },
+      { pathPattern: "*.svg", targetOriginId: "static" },
+    ]);
+  });
+
+  it("the stack attaches the svg policy to the SVG behaviors ahead of /media/*, the site policy everywhere else", () => {
+    const src = stack("aws");
+    expect(src).toContain('...cloudFrontHeadersPolicy("site")');
+    expect(src).toContain('...cloudFrontHeadersPolicy("svg")');
+    expect(src).toContain("...CLOUDFRONT_SVG_BEHAVIORS.map(");
+    expect(src.match(/responseHeadersPolicyId: siteHeadersPolicy\.id/g)).toHaveLength(2);
+    expect(src).toContain("responseHeadersPolicyId: svgHeadersPolicy.id");
+    expect(src.indexOf("...CLOUDFRONT_SVG_BEHAVIORS.map(")).toBeLessThan(
+      src.indexOf('pathPattern: "/media/*"'),
+    );
+  });
+});
+
+describe("Azure Front Door security rule set", () => {
+  const rules = frontDoorSecurityRules();
+
+  it("nosniff on every response (no condition)", () => {
+    const nosniff = rules.find((r) => r.ruleName === "nosniff");
+    expect(nosniff && "conditions" in nosniff).toBe(false);
+    expect(nosniff?.actions).toEqual([
+      {
+        name: "ModifyResponseHeader",
+        parameters: {
+          typeName: "DeliveryRuleHeaderActionParameters",
+          headerAction: "Overwrite",
+          headerName: "X-Content-Type-Options",
+          value: NOSNIFF,
+        },
+      },
+    ]);
+  });
+
+  it("the CSP when the file extension is svg, compared lower-cased", () => {
+    const svg = rules.find((r) => r.ruleName === "svgCsp");
+    expect(svg && "conditions" in svg ? svg.conditions : []).toEqual([
+      {
+        name: "UrlFileExtension",
+        parameters: {
+          typeName: "DeliveryRuleUrlFileExtensionMatchConditionParameters",
+          operator: "Equal",
+          negateCondition: false,
+          matchValues: ["svg"],
+          transforms: ["Lowercase"],
+        },
+      },
+    ]);
+    expect(svg?.actions[0]?.parameters).toMatchObject({
+      headerName: "Content-Security-Policy",
+      value: SVG_DOCUMENT_CSP,
+    });
+  });
+
+  it("rules keep processing so both apply, with distinct orders", () => {
+    expect(rules.every((r) => r.matchProcessingBehavior === "Continue")).toBe(true);
+    expect(new Set(rules.map((r) => r.order)).size).toBe(rules.length);
+  });
+
+  it("the stack creates the set and attaches it to the static route next to the redirects", () => {
+    const src = stack("azure");
+    expect(src).toContain("ruleSetName: FRONT_DOOR_SECURITY_RULE_SET");
+    expect(src).toContain("for (const rule of frontDoorSecurityRules())");
+    expect(src).toContain("ruleSets: [{ id: redirectRuleSet.id }, { id: securityRuleSet.id }]");
+    expect(FRONT_DOOR_SECURITY_RULE_SET).not.toBe("caeloRedirects");
+  });
+});
+
+describe("GCP static backend bucket", () => {
+  it("adds nosniff to every response", () => {
+    expect(GCP_STATIC_RESPONSE_HEADERS).toEqual([`X-Content-Type-Options: ${NOSNIFF}`]);
+  });
+
+  it("the stack sets the headers on the static backend bucket", () => {
+    expect(stack("gcp")).toContain("customResponseHeaders: [...GCP_STATIC_RESPONSE_HEADERS]");
+  });
+});

package/src/static-security-headers.ts

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #891 — the public site's security response headers at each provider's
+ * Tier-1 edge (CLAUDE.md §11.B): every response `nosniff`, every SVG the
+ * sandboxing CSP (`SVG_DOCUMENT_CSP`, @caelo-cms/shared). An uploaded SVG
+ * opened directly is a document that runs script in the site's origin —
+ * the origin that also serves `/api/*` through the same load balancer — so
+ * the header must come from the edge that serves the file, not from page
+ * HTML. `sanitizeSvg` at upload stays the first line; this is the second.
+ *
+ * The provider configs below are plain data the stacks pass to Pulumi
+ * (imported from `dist/`, so this file stays free of provider SDKs), and
+ * the unit tests pin them:
+ *
+ *   - AWS: CloudFront response headers policies — one with nosniff on every
+ *     behavior, one adding the CSP on `*.svg` behaviors of both S3 origins.
+ *   - Azure: a stack-owned Front Door rule set next to the deploy-owned
+ *     redirects set — nosniff on every response, the CSP when the URL file
+ *     extension is `svg`.
+ *   - Self-hosted: the Caddyfile generator (caddy.ts).
+ *   - Firebase Hosting: version-config headers the publisher writes
+ *     (admin-core static-publisher-firebase.ts).
+ *   - GCP (`gcp` stack): the static backend bucket's custom response header
+ *     carries nosniff; the CSP cannot be attached per file on that load
+ *     balancer (see `gcsObjectMetadata` in admin-core for why), so SVG
+ *     objects are stored `Content-Disposition: attachment` instead and the
+ *     converge backfills them (static-svg-gcp.ts).
+ */
+
+import { NOSNIFF, SVG_DOCUMENT_CSP } from "@caelo-cms/shared";
+
+// ===========================================================================
+// GCP — Cloud CDN backend bucket
+// ===========================================================================
+
+/**
+ * `customResponseHeaders` of the `gcp` stack's static backend bucket, in
+ * the `Name: value` form the Compute API and `gcloud compute backend-buckets
+ * update --custom-response-header` take. The converge (stack-converge.ts)
+ * brings existing installs to exactly this list.
+ */
+export const GCP_STATIC_RESPONSE_HEADERS: readonly string[] = [
+  `X-Content-Type-Options: ${NOSNIFF}`,
+];
+
+// ===========================================================================
+// AWS — CloudFront
+// ===========================================================================
+
+/** The two response headers policies the AWS stack attaches. */
+export type CloudFrontHeadersPolicyKind = "site" | "svg";
+
+/**
+ * `aws.cloudfront.ResponseHeadersPolicy` arguments (minus `name`). `site`
+ * goes on every cache behavior; `svg` on the `*.svg` behaviors
+ * ({@link CLOUDFRONT_SVG_BEHAVIORS}). `override: true` so an origin header
+ * can never weaken them.
+ */
+export function cloudFrontHeadersPolicy(kind: CloudFrontHeadersPolicyKind): {
+  readonly comment: string;
+  readonly securityHeadersConfig: {
+    readonly contentTypeOptions: { readonly override: true };
+    readonly contentSecurityPolicy?: {
+      readonly contentSecurityPolicy: string;
+      readonly override: true;
+    };
+  };
+} {
+  if (kind === "site") {
+    return {
+      comment: "Caelo static site: nosniff on every response (#891)",
+      securityHeadersConfig: { contentTypeOptions: { override: true } },
+    };
+  }
+  return {
+    comment: "Caelo static site: sandboxing CSP on SVG documents (#891)",
+    securityHeadersConfig: {
+      contentTypeOptions: { override: true },
+      contentSecurityPolicy: { contentSecurityPolicy: SVG_DOCUMENT_CSP, override: true },
+    },
+  };
+}
+
+/**
+ * The SVG cache behaviors, in CloudFront precedence order (first match
+ * wins): `/media/*.svg` must come before the generic `*.svg` (which would
+ * route media SVGs to the static origin) and both before `/media/*`.
+ * CloudFront path patterns are case-sensitive; the static generator writes
+ * every media extension in lower case (media-asset-path.ts).
+ */
+export const CLOUDFRONT_SVG_BEHAVIORS: ReadonlyArray<{
+  readonly pathPattern: string;
+  readonly targetOriginId: "media" | "static";
+}> = [
+  { pathPattern: "/media/*.svg", targetOriginId: "media" },
+  { pathPattern: "*.svg", targetOriginId: "static" },
+];
+
+// ===========================================================================
+// Azure — Front Door rules engine
+// ===========================================================================
+
+/** Name of the stack-owned Front Door rule set (the redirects set is the deploy's). */
+export const FRONT_DOOR_SECURITY_RULE_SET = "caeloSecurityHeaders";
+
+/** One `ModifyResponseHeader` action that overwrites `headerName`. */
+function overwriteResponseHeader(headerName: string, value: string) {
+  return {
+    name: "ModifyResponseHeader" as const,
+    parameters: {
+      typeName: "DeliveryRuleHeaderActionParameters" as const,
+      headerAction: "Overwrite",
+      headerName,
+      value,
+    },
+  };
+}
+
+/**
+ * The rules of {@link FRONT_DOOR_SECURITY_RULE_SET}, as `azure.cdn.Rule`
+ * arguments (minus the resource group / profile / rule set the stack
+ * fills in). A rule without conditions runs on every request; the SVG rule
+ * matches the URL's file extension lower-cased, so `.SVG` is covered.
+ * `Continue` lets both rules (and the redirects set) apply.
+ */
+export function frontDoorSecurityRules() {
+  return [
+    {
+      ruleName: "nosniff",
+      order: 1,
+      matchProcessingBehavior: "Continue",
+      actions: [overwriteResponseHeader("X-Content-Type-Options", NOSNIFF)],
+    },
+    {
+      ruleName: "svgCsp",
+      order: 2,
+      matchProcessingBehavior: "Continue",
+      conditions: [
+        {
+          name: "UrlFileExtension" as const,
+          parameters: {
+            typeName: "DeliveryRuleUrlFileExtensionMatchConditionParameters" as const,
+            operator: "Equal",
+            negateCondition: false,
+            matchValues: ["svg"],
+            transforms: ["Lowercase"],
+          },
+        },
+      ],
+      actions: [overwriteResponseHeader("Content-Security-Policy", SVG_DOCUMENT_CSP)],
+    },
+  ];
+}

package/src/static-svg-gcp.test.ts

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #891 — the converge's backfill of a `gcp` install's live SVGs: patch the
+ * ones not yet served as downloads, then purge Cloud CDN once.
+ */
+
+import { describe, expect, it } from "bun:test";
+import type { GcloudResult } from "./gcloud.js";
+import type { InstallTarget } from "./stack-converge.js";
+import { ensureSvgDownloads, svgObjectsMissingDisposition } from "./static-svg-gcp.js";
+
+const ok = (stdout = ""): GcloudResult => ({ ok: true, stdout, stderr: "", exitCode: 0 });
+const fail = (stderr: string): GcloudResult => ({ ok: false, stdout: "", stderr, exitCode: 1 });
+
+const gcp: InstallTarget = {
+  provider: "gcp",
+  projectId: "acme",
+  region: "europe-west1",
+  env: "production",
+  services: { admin: "caelo-production-admin-1", gateway: "caelo-production-gateway-2" },
+};
+
+const URL_A = "gs://acme-caelo-production-static/_assets/a.0123456789abcdef.svg";
+const URL_B = "gs://acme-caelo-production-static/_assets/brand/b.0123456789abcdef.svg";
+
+/** Answers by the longest matching command prefix; records every call. */
+function fakeGcloud(answers: Record<string, GcloudResult>) {
+  const calls: string[] = [];
+  const run = async (args: string[]) => {
+    const line = args.join(" ");
+    calls.push(line);
+    const key = Object.keys(answers)
+      .filter((k) => line.startsWith(k))
+      .sort((a, b) => b.length - a.length)[0];
+    return key ? (answers[key] as GcloudResult) : ok();
+  };
+  return { run, calls };
+}
+
+const listing = (...objects: object[]) => ok(JSON.stringify(objects));
+
+describe("svgObjectsMissingDisposition", () => {
+  it("returns the objects not served as attachment", () => {
+    expect(
+      svgObjectsMissingDisposition(
+        JSON.stringify([
+          { storage_url: URL_A, content_disposition: "attachment" },
+          { storage_url: URL_B },
+          { storage_url: "gs://x/c.svg", content_disposition: "inline" },
+        ]),
+      ),
+    ).toEqual([URL_B, "gs://x/c.svg"]);
+  });
+
+  it("treats empty output as no objects and refuses anything that is not a listing", () => {
+    expect(svgObjectsMissingDisposition("")).toEqual([]);
+    expect(() => svgObjectsMissingDisposition("{}")).toThrow("not a JSON list");
+    expect(() => svgObjectsMissingDisposition('[{"name":"a.svg"}]')).toThrow("storage_url");
+  });
+});
+
+describe("ensureSvgDownloads", () => {
+  it("patches the SVGs a pre-#891 install serves inline, then purges the CDN once", async () => {
+    const { run, calls } = fakeGcloud({
+      "storage objects list": listing(
+        { storage_url: URL_A },
+        { storage_url: URL_B, content_disposition: "attachment" },
+      ),
+      "compute url-maps list": ok("caelo-production-url-map-1a2b3c\n"),
+    });
+    const outcome = await ensureSvgDownloads(gcp, run);
+    expect(outcome.status).toBe("applied");
+    expect(outcome.onFailure).toBe("warn");
+    expect(calls).toEqual([
+      "storage objects list gs://acme-caelo-production-static/**.svg --project=acme --format=json",
+      `storage objects update ${URL_A} --content-disposition=attachment --project=acme`,
+      "compute url-maps list --global --project=acme --filter=name~^caelo-production-url-map --format=value(name)",
+      "compute url-maps invalidate-cdn-cache caelo-production-url-map-1a2b3c --path=/* --global --async --project=acme --quiet",
+    ]);
+  });
+
+  it("does nothing (no purge) when every SVG is already a download", async () => {
+    const { run, calls } = fakeGcloud({
+      "storage objects list": listing({ storage_url: URL_A, content_disposition: "attachment" }),
+    });
+    expect((await ensureSvgDownloads(gcp, run)).status).toBe("present");
+    expect(calls).toHaveLength(1);
+  });
+
+  it("is present for an install without any SVG", async () => {
+    const { run } = fakeGcloud({
+      "storage objects list": fail(
+        "ERROR: (gcloud.storage.objects.list) One or more URLs matched no objects.",
+      ),
+    });
+    expect((await ensureSvgDownloads(gcp, run)).status).toBe("present");
+  });
+
+  it("patches in batches so no argv grows with the site", async () => {
+    const many = Array.from({ length: 250 }, (_, i) => ({
+      storage_url: `gs://acme-caelo-production-static/_assets/i${i}.svg`,
+    }));
+    const { run, calls } = fakeGcloud({
+      "storage objects list": ok(JSON.stringify(many)),
+      "compute url-maps list": ok("caelo-production-url-map-1\n"),
+    });
+    expect((await ensureSvgDownloads(gcp, run)).status).toBe("applied");
+    const updates = calls.filter((c) => c.startsWith("storage objects update"));
+    expect(updates).toHaveLength(3);
+    expect(updates[0]?.split(" gs://")).toHaveLength(101);
+  });
+
+  it("warns with the manual next step when the patch or the purge fails", async () => {
+    const patchFails = fakeGcloud({
+      "storage objects list": listing({ storage_url: URL_A }),
+      "storage objects update": fail("PERMISSION_DENIED"),
+    });
+    const patched = await ensureSvgDownloads(gcp, patchFails.run);
+    expect(patched).toMatchObject({ status: "failed", onFailure: "warn" });
+    expect(patched.error).toContain("PERMISSION_DENIED");
+    expect(patchFails.calls.some((c) => c.includes("invalidate-cdn-cache"))).toBe(false);
+
+    const purgeFails = fakeGcloud({
+      "storage objects list": listing({ storage_url: URL_A }),
+      "compute url-maps list": ok("caelo-production-url-map-1\n"),
+      "compute url-maps invalidate-cdn-cache": fail("rate limited"),
+    });
+    const purged = await ensureSvgDownloads(gcp, purgeFails.run);
+    expect(purged.status).toBe("failed");
+    expect(purged.error).toContain("invalidate-cdn-cache");
+  });
+});

package/src/static-svg-gcp.ts

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #891 — backfill of the `gcp` stack's live SVG objects, run by the converge
+ * (`ensureStackInvariants`, stack-converge.ts) on every upgrade.
+ *
+ * On GCS the publisher stores every SVG with `Content-Disposition:
+ * attachment` (admin-core `gcsObjectMetadata` says why that, not a CSP), but
+ * the hash-skip never rewrites an unchanged object, and Cloud CDN keeps the
+ * responses it cached for up to a year (`STATIC_CDN_POLICY.maxTtl`). So the
+ * converge patches every live SVG that lacks the header and, when it patched
+ * any, invalidates the CDN cache once so the edge stops serving the old
+ * responses. A second run finds nothing to patch and purges nothing.
+ *
+ * Failures warn instead of aborting the upgrade: the publisher's
+ * CACHE_POLICY_VERSION bump rewrites every object on the next Publish live
+ * anyway, and the report names what is left to do.
+ */
+
+import type { GcloudRunner } from "./gcloud-retry.js";
+import { gcpBucketName, gcpNamePrefix } from "./gcp-names.js";
+import type { InstallTarget, InvariantOutcome } from "./stack-converge.js";
+
+/** `gcloud storage objects update` takes many URLs; keep each argv bounded. */
+const UPDATE_BATCH = 100;
+
+/** gcloud's answer when a wildcard matches nothing (an install with no SVGs). */
+const NO_MATCH = /matched no objects|No URLs matched|One or more URLs matched no/i;
+
+/** One object of `gcloud storage objects list --format=json` (standardised keys). */
+interface ListedObject {
+  readonly storage_url?: unknown;
+  readonly content_disposition?: unknown;
+}
+
+/**
+ * The `gs://…` URLs in `listJson` (gcloud's standardised object listing)
+ * that are not yet served as downloads.
+ *
+ * @throws when the output is not the JSON list gcloud prints.
+ */
+export function svgObjectsMissingDisposition(listJson: string): string[] {
+  const parsed = JSON.parse(listJson.trim() === "" ? "[]" : listJson) as unknown;
+  if (!Array.isArray(parsed)) throw new Error("the object listing is not a JSON list");
+  const out: string[] = [];
+  for (const o of parsed as ListedObject[]) {
+    if (typeof o.storage_url !== "string") {
+      throw new Error("an object in the listing has no storage_url");
+    }
+    if (o.content_disposition !== "attachment") out.push(o.storage_url);
+  }
+  return out;
+}
+
+/** Patch the live SVGs of a `gcp` install and purge the CDN when any changed. */
+export async function ensureSvgDownloads(
+  install: InstallTarget,
+  run: GcloudRunner,
+): Promise<InvariantOutcome> {
+  const bucket = gcpBucketName(install.projectId, install.env, "static");
+  const base = {
+    id: `SVGs in gs://${bucket} served as downloads`,
+    onFailure: "warn" as const,
+    why: "an uploaded SVG opened on the live site downloads instead of running script on the site's origin (#891)",
+  };
+  const project = `--project=${install.projectId}`;
+  const failed = (error: string): InvariantOutcome => ({
+    ...base,
+    status: "failed",
+    error: `${error}\n    The next Publish live rewrites every SVG with the header; purge the CDN afterwards (gcloud compute url-maps invalidate-cdn-cache <url-map> --path="/*" --global).`,
+  });
+
+  const list = await run([
+    "storage",
+    "objects",
+    "list",
+    `gs://${bucket}/**.svg`,
+    project,
+    "--format=json",
+  ]);
+  if (!list.ok) {
+    return NO_MATCH.test(list.stderr)
+      ? { ...base, status: "present" }
+      : failed(`list SVG objects: ${list.stderr.trim()}`);
+  }
+  let pending: string[];
+  try {
+    pending = svgObjectsMissingDisposition(list.stdout);
+  } catch (e) {
+    return failed(`list SVG objects: ${(e as Error).message}`);
+  }
+  if (pending.length === 0) return { ...base, status: "present" };
+
+  for (let i = 0; i < pending.length; i += UPDATE_BATCH) {
+    const update = await run([
+      "storage",
+      "objects",
+      "update",
+      ...pending.slice(i, i + UPDATE_BATCH),
+      "--content-disposition=attachment",
+      project,
+    ]);
+    if (!update.ok) return failed(`set Content-Disposition: ${update.stderr.trim()}`);
+  }
+
+  // The edge still holds the old responses. One site-wide purge: SVGs sit
+  // under many paths, and this only runs when objects were just patched.
+  const maps = await run([
+    "compute",
+    "url-maps",
+    "list",
+    "--global",
+    project,
+    `--filter=name~^${gcpNamePrefix(install.env)}-url-map`,
+    "--format=value(name)",
+  ]);
+  const urlMap = maps.ok ? maps.stdout.trim().split("\n")[0]?.trim() : "";
+  if (!urlMap) {
+    return failed(
+      `patched ${pending.length} SVG(s), but found no URL map to purge: ${maps.ok ? "none listed" : maps.stderr.trim()}`,
+    );
+  }
+  const purge = await run([
+    "compute",
+    "url-maps",
+    "invalidate-cdn-cache",
+    urlMap,
+    "--path=/*",
+    "--global",
+    "--async",
+    project,
+    "--quiet",
+  ]);
+  if (!purge.ok) {
+    return failed(
+      `patched ${pending.length} SVG(s), but the CDN purge failed: ${purge.stderr.trim()}`,
+    );
+  }
+  return { ...base, status: "applied" };
+}