feat(core): allow validation plugins to create new files in cloud assembly (#38007)

## Summary

- Changes the validation plugin integrity check from fingerprinting the entire `outdir` to snapshotting only pre-existing file hashes before plugins run.
- Plugins may now **create new files** in the cloud assembly directory (e.g. SARIF reports, custom output files) without triggering the "modified the cloud assembly" error.
- **Modifications** or **deletions** of pre-existing files are still caught and throw.
- Replaces `FileSystem.fingerprint` with per-file SHA-256 hashes because `fingerprint` computes a single hash over the entire directory tree, making it impossible to distinguish new files from modifications to existing ones.

The plugin contract is updated from "plugins cannot modify the cloud assembly" to "plugins cannot modify or delete files that existed in the cloud assembly prior to plugin execution."

## Test plan

- [x] Existing test: `plugin tries to modify a template` — still throws (modification of pre-existing file)
- [x] New test: `plugin that writes new files to assembly is allowed` — creates a file, no error, file contents verified
- [x] New test: `plugin that deletes pre-existing file is caught` — deletion detected and throws
- [x] Full validation test suite passes (50/50)

Author: kaizencc

packages/aws-cdk-lib/core/lib/private/synthesis.ts

@@ -1,3 +1,4 @@
+import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as private_cxapi from '@aws-cdk/cloud-assembly-api';
@@ -17,7 +18,6 @@ import { App } from '../app';
 import { _aspectTreeRevisionReader, AspectApplication, AspectPriority, Aspects } from '../aspect';
 import { AssumptionError, UnscopedValidationError } from '../errors';
 import { FeatureFlags } from '../feature-flags';
-import { FileSystem } from '../fs';
 import { Stack } from '../stack';
 import type { ISynthesisSession } from '../stack-synthesizers/types';
 import type { StageSynthesisOptions } from '../stage';
@@ -105,7 +105,6 @@ function getAssemblies(root: App, rootAssembly: private_cxapi.CloudAssembly): Ma
  */
 function invokeValidationPlugins(root: IConstruct, outdir: string, assembly: private_cxapi.CloudAssembly) {
   if (!App.isApp(root)) return;
-  let hash: string | undefined;
   const assemblies = getAssemblies(root, assembly);
   const templatePathsByPlugin: Map<IPolicyValidationPlugin, string[]> = new Map();
   visitAssemblies(root, 'post', construct => {
@@ -142,9 +141,9 @@ function invokeValidationPlugins(root: IConstruct, outdir: string, assembly: pri
   // eslint-disable-next-line no-console
   console.error('Performing Policy Validations\n');
 
-  if (templatePathsByPlugin.size > 0) {
-    hash = FileSystem.fingerprint(outdir);
-  }
+  // Snapshot pre-existing files so we can detect modifications while still
+  // allowing plugins to create new files in the assembly directory.
+  const preExistingFileHashes = snapshotFileHashes(outdir);
 
   // Run all plugins through the same loop
   const reports: NamedValidationPluginReport[] = [];
@@ -163,7 +162,7 @@ function invokeValidationPlugins(root: IConstruct, outdir: string, assembly: pri
         },
       });
     }
-    if (hash && FileSystem.fingerprint(outdir) !== hash) {
+    if (hasModifiedPreExistingFiles(preExistingFileHashes)) {
       throw new AssumptionError(lit`IllegalOperationValidationPlugin`, `Illegal operation: validation plugin '${plugin.name}' modified the cloud assembly`);
     }
   }
@@ -565,3 +564,41 @@ function getBooleanContext(root: IConstruct, key: string, defaultValue: boolean)
   if (raw === undefined) return defaultValue;
   return raw !== false && raw !== 'false';
 }
+
+function collectFilePaths(dir: string): string[] {
+  const results: string[] = [];
+  function walk(current: string) {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else {
+        results.push(full);
+      }
+    }
+  }
+  walk(dir);
+  return results;
+}
+
+function hashFile(filePath: string): string {
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function snapshotFileHashes(dir: string): Map<string, string> {
+  const hashes = new Map<string, string>();
+  for (const filePath of collectFilePaths(dir)) {
+    hashes.set(filePath, hashFile(filePath));
+  }
+  return hashes;
+}
+
+function hasModifiedPreExistingFiles(snapshot: Map<string, string>): boolean {
+  for (const [filePath, originalHash] of snapshot) {
+    if (!fs.existsSync(filePath) || hashFile(filePath) !== originalHash) {
+      return true;
+    }
+  }
+  return false;
+}

packages/aws-cdk-lib/core/test/validation/validation.test.ts

@@ -609,6 +609,50 @@ Policy Validation Report Summary
     }).toThrow(/Illegal operation: validation plugin 'rogue-plugin' modified the cloud assembly/);
   });
 
+  test('plugin that writes new files to assembly is allowed', () => {
+    const app = new core.App({
+      policyValidationBeta1: [
+        {
+          name: 'file-writer-plugin',
+          validate(context: core.IPolicyValidationContextBeta1) {
+            const assemblyDir = path.dirname(context.templatePaths[0]);
+            fs.writeFileSync(path.join(assemblyDir, 'plugin-output.json'), '{"result":"ok"}');
+            return { success: true, violations: [] };
+          },
+        },
+      ],
+    });
+    const stack = new core.Stack(app);
+    new core.CfnResource(stack, 'DefaultResource', {
+      type: 'Test::Resource::Fake',
+      properties: { result: 'success' },
+    });
+    expect(() => app.synth()).not.toThrow();
+    const outputFile = path.join(app.outdir, 'plugin-output.json');
+    expect(fs.existsSync(outputFile)).toBe(true);
+    expect(JSON.parse(fs.readFileSync(outputFile, 'utf-8'))).toEqual({ result: 'ok' });
+  });
+
+  test('plugin that deletes pre-existing file is caught', () => {
+    const app = new core.App({
+      policyValidationBeta1: [
+        {
+          name: 'deleter-plugin',
+          validate(context: core.IPolicyValidationContextBeta1) {
+            fs.unlinkSync(context.templatePaths[0]);
+            return { success: true, violations: [] };
+          },
+        },
+      ],
+    });
+    const stack = new core.Stack(app);
+    new core.CfnResource(stack, 'DefaultResource', {
+      type: 'Test::Resource::Fake',
+      properties: { result: 'success' },
+    });
+    expect(() => app.synth()).toThrow(/Illegal operation: validation plugin 'deleter-plugin' modified the cloud assembly/);
+  });
+
   test('failSynthOnValidationErrors=false writes JSON but does not print or fail', () => {
     const app = new core.App({
       policyValidationBeta1: [