feat(@angular/build): emit debug ids for stable subresource integrity hashes

Enable generating sub-resource integrity hashes when using error tracking tools relying on Debug IDs linking generated code files with source maps.

Closes angular#33108
fix: persist formatting of source map JSON

fix: improve source map comment detection and test fix

format

fix import error

fix imports

Author: IchordeDionysos

packages/angular/build/src/builders/application/execute-post-bundle.ts

@@ -30,6 +30,7 @@ import {
 } from '../../utils/server-rendering/models';
 import { prerenderPages } from '../../utils/server-rendering/prerender';
 import { augmentAppWithServiceWorkerEsbuild } from '../../utils/service-worker';
+import { injectDebugIds } from './inject-debug-ids';
 import { INDEX_HTML_CSR, INDEX_HTML_SERVER, NormalizedApplicationBuildOptions } from './options';
 import { OutputMode } from './schema';
 
@@ -79,6 +80,14 @@ export async function executePostBundleSteps(
     partialSSRBuild,
   } = options;
 
+  // Embed ECMA-426 Debug IDs into JS/source-map pairs before any consumer reads the bytes (in
+  // particular `generateIndexHtml` below, which computes SRI hashes from the on-disk content).
+  // Doing this here also covers the i18n path, where this function is invoked once per locale
+  // with locale-specific output files. Files without a source map sibling are skipped.
+  if (sourcemapOptions.scripts) {
+    injectDebugIds(outputFiles);
+  }
+
   // Index HTML content without CSS inlining to be used for server rendering (AppShell, SSG and SSR).
   // NOTE: Critical CSS inlining is deliberately omitted here, as it will be handled during server rendering.
   // Additionally, when using prerendering or AppShell, the index HTML file may be regenerated.

packages/angular/build/src/builders/application/inject-debug-ids.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { BuildOutputFile, BuildOutputFileType } from '../../tools/esbuild/bundler-files';
+import {
+  generateDebugId,
+  injectDebugIdIntoJs,
+  injectDebugIdIntoSourceMap,
+} from '../../utils/debug-id';
+
+/**
+ * Embeds an ECMA-426 Debug ID into every browser JavaScript output that has a
+ * matching source map sibling.
+ *
+ * The Debug ID is derived deterministically (UUIDv5) from the source map bytes
+ * so rebuilds of the same source produce the same ID. The JS file gets a
+ * `//# debugId=<uuid>` comment placed above any existing
+ * `//# sourceMappingURL=` line and the source map JSON gets a top-level
+ * `"debugId"` field. Together they make build artifacts self-identifying as
+ * proposed by https://github.com/tc39/ecma426/blob/main/proposals/debug-id.md.
+ */
+export function injectDebugIds(outputFiles: BuildOutputFile[]): void {
+  const filesByPath = new Map<string, BuildOutputFile>();
+  for (const file of outputFiles) {
+    filesByPath.set(file.path, file);
+  }
+
+  const encoder = new TextEncoder();
+
+  for (const file of outputFiles) {
+    if (file.type !== BuildOutputFileType.Browser || !file.path.endsWith('.js')) {
+      continue;
+    }
+
+    const map = filesByPath.get(`${file.path}.map`);
+    if (!map) {
+      continue;
+    }
+
+    const id = generateDebugId(map.contents);
+    file.contents = encoder.encode(injectDebugIdIntoJs(file.text, id));
+    map.contents = encoder.encode(injectDebugIdIntoSourceMap(map.text, id));
+  }
+}

packages/angular/build/src/builders/application/tests/options/subresource-integrity_spec.ts

@@ -83,6 +83,83 @@ describeBuilder(buildApplication, APPLICATION_BUILDER_INFO, (harness) => {
       expectNoLog(logs, /subresource-integrity/);
     });
 
+    it(`embeds an ECMA-426 debugId in JS and source map and the integrity matches`, async () => {
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        subresourceIntegrity: true,
+        sourceMap: { scripts: true },
+      });
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBe(true);
+
+      const distDir = workspacePath('dist/browser');
+      const allEntries = readdirSync(distDir);
+      const jsFiles = allEntries.filter(
+        (f) => f.endsWith('.js') && allEntries.includes(`${f}.map`),
+      );
+      expect(jsFiles.length).toBeGreaterThan(0);
+
+      const debugIdRe = /\/\/# debugId=([^\r\n]*)/;
+      const indexHtml = harness.readFile('dist/browser/index.html');
+      const importmapMatch = indexHtml.match(/<script type="importmap">([^<]+)<\/script>/);
+      const importmap = importmapMatch
+        ? (JSON.parse(importmapMatch[1]) as { integrity: Record<string, string> })
+        : { integrity: {} };
+
+      for (const file of jsFiles) {
+        const js = readFileSync(join(distDir, file), 'utf-8');
+        const map = JSON.parse(readFileSync(join(distDir, `${file}.map`), 'utf-8'));
+
+        const idMatch = js.match(debugIdRe);
+        expect(idMatch).withContext(`debugId comment in ${file}`).not.toBeNull();
+        const id = idMatch![1];
+
+        // ECMA-426: source map carries the same id under "debugId".
+        expect(map.debugId).withContext(`debugId field in ${file}.map`).toBe(id);
+
+        // Integrity hash recorded in index.html (initial) or in the importmap
+        // (lazy) must match the bytes written to disk *after* debug-id
+        // injection, otherwise SRI validation in the browser will fail.
+        const onDisk = readFileSync(join(distDir, file));
+        const expectedSri = `sha384-${createHash('sha384').update(onDisk).digest('base64')}`;
+        const escapedFile = file.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const escapedSri = expectedSri.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const inHeadIntegrity = new RegExp(
+          `(?:src|href)="${escapedFile}"[^>]*integrity="${escapedSri}"`,
+        );
+        const fromImportmap = importmap.integrity[`/${file}`];
+        expect(inHeadIntegrity.test(indexHtml) || fromImportmap === expectedSri)
+          .withContext(`integrity for ${file} must match on-disk bytes`)
+          .toBeTrue();
+      }
+    });
+
+    it(`places the debugId comment immediately above sourceMappingURL`, async () => {
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        sourceMap: { scripts: true },
+      });
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBe(true);
+
+      const distDir = workspacePath('dist/browser');
+      const allEntries = readdirSync(distDir);
+      const jsFiles = allEntries.filter(
+        (f) => f.endsWith('.js') && allEntries.includes(`${f}.map`),
+      );
+      expect(jsFiles.length).toBeGreaterThan(0);
+
+      const ordering = /\/\/\s*#\s*debugId=[0-9a-f-]+\s*\n\s*\/\/\s*#\s*sourceMappingURL=/;
+      for (const file of jsFiles) {
+        const js = readFileSync(join(distDir, file), 'utf-8');
+        expect(ordering.test(js))
+          .withContext(`debugId must precede sourceMappingURL in ${file}`)
+          .toBeTrue();
+      }
+    });
+
     it(`emits an importmap with integrity for lazy chunks when 'true'`, async () => {
       await harness.writeFiles(lazyModuleFiles);
       await harness.writeFiles(lazyModuleFnImport);

packages/angular/build/src/utils/debug-id.ts

@@ -0,0 +1,98 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * Fixed RFC 4122 namespace UUID used to derive deterministic UUIDv5 build/Debug IDs.
+ * Treated as 16 raw bytes when fed into the SHA-1 of `namespace || name`.
+ *
+ * The exact value is arbitrary but must remain stable across releases so that
+ * the same source map content always yields the same Debug ID.
+ */
+const ANGULAR_BUILD_NAMESPACE = Buffer.from('6f9619ff8b86d011b42d00cf4fc964ff', 'hex');
+
+/**
+ * Generates a deterministic UUIDv5 (RFC 4122 §4.3) Debug ID from the given name bytes.
+ *
+ * Determinism is recommended by the ECMA-426 "Source Map Debug ID" proposal
+ * (https://github.com/tc39/ecma426/blob/main/proposals/debug-id.md) so that the
+ * produced artifacts are stable across builds with the same source content.
+ *
+ * @param name Bytes that uniquely identify the artifact (typically the source map content).
+ * @returns A canonical UUIDv5 string (lowercase, hyphenated).
+ */
+export function generateDebugId(name: string | Uint8Array): string {
+  const sha = createHash('sha1').update(ANGULAR_BUILD_NAMESPACE).update(name).digest();
+
+  // Set version (5) in the high nibble of byte 6.
+  sha[6] = (sha[6] & 0x0f) | 0x50;
+  // Set RFC 4122 variant bits (10xx) in byte 8.
+  sha[8] = (sha[8] & 0x3f) | 0x80;
+
+  const h = sha.toString('hex');
+
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
+}
+
+/** Pattern matching an existing `//# debugId=<uuid>` comment anywhere in the file. */
+const DEBUG_ID_COMMENT = /\n\/\/# debugId=[^\r\n]*\n?/;
+
+/** Pattern matching the `//# sourceMappingURL=` comment, used to position the debug-id line. */
+const SOURCE_MAPPING_URL_COMMENT = /\n\/\/# sourceMappingURL=[^\r\n]*\s*$/;
+
+/**
+ * Inserts (or replaces) a `//# debugId=<id>` comment in the given JavaScript text.
+ *
+ * Per ECMA-426, the comment must appear within the last 5 lines and SHOULD be
+ * placed immediately above any `//# sourceMappingURL=` comment so that existing
+ * tools that only consult the final line still find the source-map URL.
+ */
+export function injectDebugIdIntoJs(text: string, id: string): string {
+  const comment = `//# debugId=${id}`;
+
+  // Replace any existing debugId comment to keep the operation idempotent.
+  if (DEBUG_ID_COMMENT.test(text)) {
+    return text.replace(DEBUG_ID_COMMENT, `\n${comment}\n`);
+  }
+
+  if (SOURCE_MAPPING_URL_COMMENT.test(text)) {
+    return text.replace(SOURCE_MAPPING_URL_COMMENT, (match) => `\n${comment}${match}`);
+  }
+
+  // No source map reference; append at the very end on its own line.
+  return text.endsWith('\n') ? `${text}${comment}\n` : `${text}\n${comment}\n`;
+}
+
+/**
+ * Sets the top-level `debugId` field on a JSON source map.
+ *
+ * Per ECMA-426, source maps embed the same Debug ID under a `debugId` key so
+ * that consumers can pair a generated file with its source map without relying
+ * on URL/path conventions.
+ */
+export function injectDebugIdIntoSourceMap(json: string, id: string): string {
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(json) as Record<string, unknown>;
+  } catch {
+    // Source map is malformed; do not corrupt it further.
+    return json;
+  }
+
+  if (parsed['debugId'] === id) {
+    return json;
+  }
+
+  parsed['debugId'] = id;
+
+  // Preserve existing pretty-print indentation when the source map is formatted.
+  const indent = json.match(/^[^{]*{\r?\n([ \t]+)/)?.[1];
+
+  return JSON.stringify(parsed, null, indent);
+}

packages/angular/build/src/utils/debug-id_spec.ts

@@ -0,0 +1,98 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { generateDebugId, injectDebugIdIntoJs, injectDebugIdIntoSourceMap } from './debug-id';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+describe('debug-id', () => {
+  describe('generateDebugId', () => {
+    it('produces a canonical UUIDv5 string', () => {
+      expect(generateDebugId('hello')).toMatch(UUID);
+      expect(generateDebugId(new TextEncoder().encode('hello'))).toMatch(UUID);
+    });
+
+    it('is deterministic for identical inputs', () => {
+      expect(generateDebugId('same content')).toBe(generateDebugId('same content'));
+    });
+
+    it('differs for different inputs', () => {
+      expect(generateDebugId('one')).not.toBe(generateDebugId('two'));
+    });
+  });
+
+  describe('injectDebugIdIntoJs', () => {
+    const id = '11111111-2222-5333-9444-555555555555';
+
+    it('inserts the debugId comment immediately above sourceMappingURL', () => {
+      const text = 'console.log(1);\n//# sourceMappingURL=foo.js.map\n';
+      const result = injectDebugIdIntoJs(text, id);
+      expect(result).toBe(
+        'console.log(1);\n//# debugId=11111111-2222-5333-9444-555555555555\n//# sourceMappingURL=foo.js.map\n',
+      );
+    });
+
+    it('appends the comment when no sourceMappingURL is present', () => {
+      const text = 'console.log(1);\n';
+      const result = injectDebugIdIntoJs(text, id);
+      expect(result).toBe('console.log(1);\n//# debugId=11111111-2222-5333-9444-555555555555\n');
+    });
+
+    it('appends a leading newline when input does not end with one', () => {
+      const text = 'console.log(1);';
+      const result = injectDebugIdIntoJs(text, id);
+      expect(result).toBe('console.log(1);\n//# debugId=11111111-2222-5333-9444-555555555555\n');
+    });
+
+    it('replaces an existing debugId comment (idempotent)', () => {
+      const original =
+        'console.log(1);\n//# debugId=00000000-0000-5000-8000-000000000000\n//# sourceMappingURL=foo.js.map\n';
+      const result = injectDebugIdIntoJs(original, id);
+      expect(result).toBe(
+        'console.log(1);\n//# debugId=11111111-2222-5333-9444-555555555555\n//# sourceMappingURL=foo.js.map\n',
+      );
+      // Re-running with the same id is a no-op.
+      expect(injectDebugIdIntoJs(result, id)).toBe(result);
+    });
+  });
+
+  describe('injectDebugIdIntoSourceMap', () => {
+    const id = '11111111-2222-5333-9444-555555555555';
+
+    it('adds a top-level debugId field', () => {
+      const map = JSON.stringify({ version: 3, sources: ['a.ts'], mappings: '' });
+      const updated = JSON.parse(injectDebugIdIntoSourceMap(map, id));
+      expect(updated.debugId).toBe(id);
+      expect(updated.version).toBe(3);
+    });
+
+    it('overwrites an existing debugId field', () => {
+      const map = JSON.stringify({ version: 3, debugId: 'old', mappings: '' });
+      const updated = JSON.parse(injectDebugIdIntoSourceMap(map, id));
+      expect(updated.debugId).toBe(id);
+    });
+
+    it('returns the original input when debugId already matches', () => {
+      const map =
+        '{\n  "version": 3,\n  "debugId": "11111111-2222-5333-9444-555555555555",\n  "mappings": ""\n}';
+      expect(injectDebugIdIntoSourceMap(map, id)).toBe(map);
+    });
+
+    it('preserves indentation when updating a pretty-printed source map', () => {
+      const map = '{\n\t"version": 3,\n\t"mappings": ""\n}';
+      expect(injectDebugIdIntoSourceMap(map, id)).toBe(
+        '{\n\t"version": 3,\n\t"mappings": "",\n\t"debugId": "11111111-2222-5333-9444-555555555555"\n}',
+      );
+    });
+
+    it('returns the original input when JSON is malformed', () => {
+      const malformed = '{ this is not json';
+      expect(injectDebugIdIntoSourceMap(malformed, id)).toBe(malformed);
+    });
+  });
+});