feat(lib): canonical asset hashes behind the canonicalAssetHashes feature flag (#323)

### Description

Closes #322. ~~Stacked on #321~~ — #321 has merged and this branch is
rebased onto current `main`; the diff is now the single canonical-hash
commit.

Adds the canonical entry-framed asset hash as a `canonicalAssetHashes`
feature flag (`FUTURE_FLAGS`: enabled for new projects by `cdktn init`,
opt-in via `cdktf.json` context for existing projects, becomes the
default at the next major). The legacy scheme — including #321's
compatibility-preserving symlink handling — stays untouched as the
default.

### The canonical representation

Modeled on git trees and Nix NAR, which serialize a full metadata model
rather than payload framing alone. Every record contains what affects
the emitted artifact:

| entry | frame |
| --- | --- |
| file | `F <mode> <relPath>\0<size>\0` + content |
| symlink | `L <mode> <relPath>\0<target byte length>\0` + target |
| directory (incl. empty) | `D <relPath>\0` |

- `<mode>` is the octal permission mask (`0o7777` bits) — exactly the
bits `archiveSync` preserves in zip external attributes, closing the
hole found in review where `0644` → `0755` changed archive bytes but not
the hash.
- Directories contribute explicit records (no mode — neither
`archiveSync` nor `copySync` preserves directory permissions), so
adding/removing an empty directory is visible.
- Entries are framed in sorted directory order with `/`-separated
relative paths; a symlink at the root is followed, matching how the
asset source path is opened when the artifact is emitted.

### Acceptance criteria from #322

Each has a dedicated test in
`packages/cdktn/test/canonical-asset-hash.test.ts`:

- [x] File rename changes the canonical hash (and a paired assertion
that legacy cannot see it)
- [x] Entry-boundary shifts change the canonical hash
- [x] File/symlink swaps and symlink retargeting change the canonical
hash
- [x] `0644` → `0755` changes the canonical hash
- [x] Adding/removing an empty directory changes the canonical hash
- [x] Identical logical trees hash deterministically (two locations +
repeated runs)
- [x] Legacy hashing remains available (flag off; `Testing.app({
enableFutureFlags: false })` covers the compat case per the
`features.ts` test rule)

### Testing

Full `cdktn` suite green (464 passing; the pre-existing environmental
`matchers.test.ts` → `toPlanSuccessfully` failure shells out to a real
`terraform plan` and is unrelated). jsii build green. Docs for the flag
are being handled separately in the docs repository (the stacked docs PR
#324 was closed in favor of that).

### Checklist

- [x] I have updated the PR title to match [CDKTN's style
guide](https://github.com/open-constructs/cdk-terrain/blob/main/CONTRIBUTING.md#pull-requests-1)
- [x] I have run the linter on my code locally
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation if
applicable (stacked docs PR follows)
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works if applicable
- [x] New and existing unit tests pass locally with my changes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: vincent de smet <vincent.drl@gmail.com>

Author: 3 people

packages/cdktn/src/features.ts

@@ -38,7 +38,26 @@ export const FAIL_ON_CONSTRUCTS_OUTSIDE_OF_STACKS =
  */
 export const VALIDATE_FUNCTION_VERSIONS = "validateFunctionVersions";
 
+/**
+ * When enabled, TerraformAsset and TerraformModuleAsset compute asset hashes
+ * with a canonical entry-framed scheme modeled on git trees and Nix NAR:
+ * every entry contributes its type, permission mask (for files and
+ * symlinks — the bits archiveSync preserves in zip external attributes),
+ * relative path, payload size, and payload, in sorted order, and
+ * directories — including empty ones — contribute explicit records. Renames,
+ * entry-boundary shifts, mode changes, empty-directory changes, and
+ * file-vs-symlink swaps all change the hash.
+ *
+ * When disabled, the legacy content-concatenation hash is kept for
+ * compatibility: trees without symlinks hash byte-identically to earlier
+ * releases, and only symlink-bearing trees (whose hashes had to change when
+ * symlink following was fixed) get a tagged hash that separates symlink
+ * metadata from file content.
+ */
+export const CANONICAL_ASSET_HASHES = "canonicalAssetHashes";
+
 export const FUTURE_FLAGS = {
   [FAIL_ON_CONSTRUCTS_OUTSIDE_OF_STACKS]: "true",
   [VALIDATE_FUNCTION_VERSIONS]: "true",
+  [CANONICAL_ASSET_HASHES]: "true",
 };

packages/cdktn/src/private/fs.ts

@@ -76,7 +76,9 @@ export function archiveSync(src: string, dest: string) {
   try {
     const files: Record<string, [Uint8Array, ZipOptions]> = {};
     const walk = (dir: string, prefix: string) => {
-      for (const entry of fs.readdirSync(dir)) {
+      // Sorted so entry order — and therefore archive bytes — cannot depend
+      // on filesystem enumeration order; matches the canonical hash walk.
+      for (const entry of fs.readdirSync(dir).sort()) {
         const full = path.join(dir, entry);
         const zipPath = prefix ? `${prefix}/${entry}` : entry;
         const stat = fs.lstatSync(full);
@@ -115,20 +117,51 @@ export function archiveSync(src: string, dest: string) {
   }
 }
 
+export interface HashPathOptions {
+  /**
+   * Use the canonical entry-framed hash instead of the legacy
+   * content-concatenation hash. Enabled through the `canonicalAssetHashes`
+   * feature flag.
+   */
+  readonly canonical?: boolean;
+  /**
+   * Frame for an archive artifact: archiveSync never emits ZIP directory
+   * entries, so canonical hashing omits directory records and the hash
+   * tracks the emitted archive bytes exactly. Non-empty directories stay
+   * visible through the relative paths of their contents. Has no effect on
+   * the legacy scheme, which never records directories.
+   */
+  readonly archive?: boolean;
+}
+
 /**
  * Compute a stable MD5 hash of a file or directory's contents.
- * File contents fold into one digest in directory-listing order, exactly as
- * earlier releases did, so trees without symlinks keep their historical
- * hashes. Symlinks are hashed by their metadata (path + target) instead of
- * being followed, so shared targets are not double-counted and cycles cannot
- * recurse; that metadata goes into a second digest, and only when symlinks
- * exist are the two combined under a tagged outer hash — the tag keeps
- * symlink metadata in a separate domain from file bytes, so a file
- * containing `foo` can never collide with a symlink targeting `foo`.
+ * In both schemes symlinks are hashed by their metadata (path + target)
+ * instead of being followed, so shared targets are not double-counted and
+ * cycles cannot recurse; a symlink at the root itself is followed, matching
+ * how the asset source path is opened when the artifact is emitted.
  * @param src - path to a file or directory to hash
+ * @param options - hash scheme selection, see {@link HashPathOptions}
  * @returns uppercased hex digest, truncated to HASH_LEN characters
  */
-export function hashPath(src: string): string {
+export function hashPath(src: string, options: HashPathOptions = {}): string {
+  const digest = options.canonical
+    ? canonicalHashPath(src, !options.archive)
+    : legacyHashPath(src);
+  return digest.slice(0, HASH_LEN).toUpperCase();
+}
+
+/**
+ * Legacy-compatible hash: file contents fold into one digest in
+ * directory-listing order, exactly as earlier releases did, so trees without
+ * symlinks keep their historical hashes. Symlink metadata goes into a second
+ * digest, and only when symlinks exist are the two combined under a tagged
+ * outer hash — the tag keeps symlink metadata in a separate domain from file
+ * bytes, so a file containing `foo` can never collide with a symlink
+ * targeting `foo`.
+ * @param src - path to a file or directory to hash
+ */
+function legacyHashPath(src: string): string {
   const content = crypto.createHash("md5");
   const links = crypto.createHash("md5");
   let linkCount = 0;
@@ -160,13 +193,70 @@ export function hashPath(src: string): string {
 
   hashRecursion(src, "", true);
   if (linkCount === 0) {
-    return content.digest("hex").slice(0, HASH_LEN).toUpperCase();
+    return content.digest("hex");
   }
   const outer = crypto.createHash("md5");
   outer.update("cdktn/asset-hash/symlinks/v1\0");
   outer.update(content.digest("hex"));
   outer.update(links.digest("hex"));
-  return outer.digest("hex").slice(0, HASH_LEN).toUpperCase();
+  return outer.digest("hex");
+}
+
+/**
+ * Canonical hash, modeled on git trees and Nix NAR: every entry is framed
+ * with everything that affects the emitted artifact —
+ *
+ * - files:      `F <mode> <relPath>\0<size>\0` + content, where `<mode>` is
+ *               the octal permission mask (`0o7777` bits) that archiveSync
+ *               preserves in zip external attributes,
+ * - symlinks:   `L <mode> <relPath>\0<target byte length>\0` + target,
+ * - directories (including empty ones, which copySync materializes):
+ *               `D <relPath>\0`, with no mode — neither archiveSync nor
+ *               copySync preserves directory permissions,
+ *
+ * in sorted directory order with `/`-separated relative paths, so renames,
+ * entry-boundary shifts, permission changes, empty-directory changes, and
+ * file-vs-symlink swaps all change the digest.
+ * @param src - path to a file or directory to hash
+ * @param includeDirectories - record directory entries; false for archive
+ * artifacts, where the emitted zip has no directory entries
+ */
+function canonicalHashPath(src: string, includeDirectories: boolean): string {
+  const hash = crypto.createHash("md5");
+
+  /**
+   * Walk `p`, framing each entry into the enclosing hash accumulator.
+   * @param p - path to walk
+   * @param relPath - path of `p` relative to the walk root, `/`-separated
+   * @param isRoot - follow a symlink only at the root, matching how the
+   * asset's own path is resolved when the artifact is emitted
+   */
+  function hashRecursion(p: string, relPath: string, isRoot = false) {
+    const stat = isRoot ? fs.statSync(p) : fs.lstatSync(p);
+    const mode = (stat.mode & PERM_MASK).toString(8);
+    if (stat.isSymbolicLink()) {
+      const target = fs.readlinkSync(p);
+      hash.update(`L ${mode} ${relPath}\0${Buffer.byteLength(target)}\0`);
+      hash.update(target);
+    } else if (stat.isFile()) {
+      const data = fs.readFileSync(p);
+      hash.update(`F ${mode} ${relPath}\0${data.length}\0`);
+      hash.update(data);
+    } else if (stat.isDirectory()) {
+      if (relPath && includeDirectories) {
+        hash.update(`D ${relPath}\0`);
+      }
+      for (const filename of fs.readdirSync(p).sort()) {
+        hashRecursion(
+          path.resolve(p, filename),
+          relPath ? `${relPath}/${filename}` : filename,
+        );
+      }
+    }
+  }
+
+  hashRecursion(src, "", true);
+  return hash.digest("hex");
 }
 
 /**

packages/cdktn/src/terraform-asset.ts

@@ -9,6 +9,7 @@ import {
   hashPath,
   findFileAboveCwd,
 } from "./private/fs";
+import { CANONICAL_ASSET_HASHES } from "./features";
 import { ISynthesisSession } from "./synthesize";
 import { addCustomSynthesis } from "./synthesize/synthesizer";
 import { TerraformStack } from "./terraform-stack";
@@ -78,7 +79,12 @@ export class TerraformAsset extends Construct {
     const stat = fs.statSync(this.sourcePath);
     const inferredType = stat.isFile() ? AssetType.FILE : AssetType.DIRECTORY;
     this.type = config.type ?? inferredType;
-    this.assetHash = config.assetHash || hashPath(this.sourcePath);
+    this.assetHash =
+      config.assetHash ||
+      hashPath(this.sourcePath, {
+        canonical: !!this.node.tryGetContext(CANONICAL_ASSET_HASHES),
+        archive: this.type === AssetType.ARCHIVE,
+      });
 
     if (stat.isFile() && this.type !== AssetType.FILE) {
       throw assetExpectsDirectory(id, config.path);

packages/cdktn/src/terraform-module-asset.ts

@@ -10,6 +10,7 @@ import * as fs from "fs";
 import { TerraformStack } from "./terraform-stack";
 import { AssetType, TerraformAsset } from "./terraform-asset";
 import { copySync, hashPath } from "./private/fs";
+import { CANONICAL_ASSET_HASHES } from "./features";
 
 const TERRAFORM_MODULE_ASSET_SYMBOL = Symbol.for("cdktf.TerraformModuleAsset");
 
@@ -66,10 +67,19 @@ export class TerraformModuleAsset extends Construct {
     }
 
     // Create asset based on tmp dir
+    const canonical = !!this.node.tryGetContext(CANONICAL_ASSET_HASHES);
     this.asset = new TerraformAsset(this, "asset", {
       path: tmpDir,
       type: AssetType.DIRECTORY,
-      assetHash: staticModuleAssetHash ?? hashPath(relativeAssetPath),
+      // The emitted asset is only the module sources copied into tmpDir, so
+      // the canonical scheme hashes that exact tree — unrelated siblings
+      // under the sources' common ancestor cannot churn the hash. Legacy
+      // keeps hashing the ancestor to preserve historical hashes.
+      assetHash:
+        staticModuleAssetHash ??
+        (canonical
+          ? hashPath(tmpDir, { canonical: true })
+          : hashPath(relativeAssetPath)),
     });
   }