@intentius/chant-lexicon-aws 0.109.0 → 0.110.0

package/src/intrinsics.ts

@@ -2,7 +2,8 @@ import { INTRINSIC_MARKER, resolveIntrinsicValue, isIntrinsic, type Intrinsic }
 import { buildInterpolatedString, defaultInterpolationSerializer } from "@intentius/chant/intrinsic-interpolation";
 import { type Declarable } from "@intentius/chant/declarable";
 import { getLogicalName } from "@intentius/chant/utils";
-import { isCondition, type Condition } from "./condition";
+import { conditionName, isCondition, type Condition } from "./condition";
+import { isMapping, mappingName, type Mapping } from "./mapping";
 
 /**
  * An operand allowed where CloudFormation expects a condition (#2068): a
@@ -17,7 +18,7 @@ function resolveConditionOperand(operand: ConditionOperand): unknown {
     return { Condition: operand };
   }
   if (isCondition(operand)) {
-    return { Condition: getLogicalName(operand) };
+    return { Condition: conditionName(operand) };
   }
   return resolveIntrinsicValue(operand);
 }
@@ -37,10 +38,14 @@ export class SubIntrinsic implements Intrinsic {
   }
 
   toJSON(): { "Fn::Sub": string } {
-    const serialize = defaultInterpolationSerializer(
+    const base = defaultInterpolationSerializer(
       (name, attr) => `\${${name}.${attr}}`,
       (ref) => `\${${ref}}`,
     );
+    // A GetAtt written by name (`GetAtt("Db", "Endpoint.Address")`) has the
+    // `${Db.Endpoint.Address}` form inside a Sub, like an attribute reference.
+    const serialize = (value: unknown): string =>
+      value instanceof GetAttIntrinsic ? `\${${value.logicalName}.${value.attribute}}` : base(value);
     return { "Fn::Sub": buildInterpolatedString(this.templateParts, this.values, serialize) };
   }
 }
@@ -92,8 +97,8 @@ export function Ref(target: string | Declarable): RefIntrinsic {
  */
 export class GetAttIntrinsic implements Intrinsic {
   readonly [INTRINSIC_MARKER] = true as const;
-  private logicalName: string;
-  private attribute: string;
+  readonly logicalName: string;
+  readonly attribute: string;
 
   constructor(logicalName: string, attribute: string) {
     this.logicalName = logicalName;
@@ -129,7 +134,7 @@ export class IfIntrinsic implements Intrinsic {
   }
 
   toJSON(): { "Fn::If": [string, unknown, unknown] } {
-    const name = typeof this.conditionName === "string" ? this.conditionName : getLogicalName(this.conditionName);
+    const name = typeof this.conditionName === "string" ? this.conditionName : conditionName(this.conditionName);
     return { "Fn::If": [name, resolveIntrinsicValue(this.valueIfTrue), resolveIntrinsicValue(this.valueIfFalse)] };
   }
 }
@@ -292,26 +297,27 @@ export function Join(delimiter: string, values: unknown[] | Intrinsic): JoinIntr
  */
 export class SelectIntrinsic implements Intrinsic {
   readonly [INTRINSIC_MARKER] = true as const;
-  private index: number;
+  private index: number | string;
   private values: unknown[] | Intrinsic;
 
-  constructor(index: number, values: unknown[] | Intrinsic) {
+  constructor(index: number | string, values: unknown[] | Intrinsic) {
     this.index = index;
     this.values = values;
   }
 
-  toJSON(): { "Fn::Select": [string, unknown] } {
+  toJSON(): { "Fn::Select": [number | string, unknown] } {
     const resolvedValues = Array.isArray(this.values)
       ? this.values.map(resolveIntrinsicValue)
-      : (this.values as Intrinsic & { toJSON(): unknown }).toJSON();
-    return { "Fn::Select": [String(this.index), resolvedValues] };
+      : resolveIntrinsicValue(this.values);
+    return { "Fn::Select": [this.index, resolvedValues] };
   }
 }
 
 /**
- * Create a Select intrinsic
+ * Create a Select intrinsic. The index is emitted as written: CloudFormation
+ * accepts `0` and `"0"`.
  */
-export function Select(index: number, values: unknown[] | Intrinsic): SelectIntrinsic {
+export function Select(index: number | string, values: unknown[] | Intrinsic): SelectIntrinsic {
   return new SelectIntrinsic(index, values);
 }
 
@@ -397,3 +403,86 @@ export class GetAZsIntrinsic implements Intrinsic {
 export function GetAZs(region?: string | Intrinsic): GetAZsIntrinsic {
   return new GetAZsIntrinsic(region);
 }
+
+/**
+ * Fn::FindInMap intrinsic function
+ * Reads the value under two keys of a declared mapping.
+ */
+export class FindInMapIntrinsic implements Intrinsic {
+  readonly [INTRINSIC_MARKER] = true as const;
+  private mapName: string | Mapping;
+  private topLevelKey: unknown;
+  private secondLevelKey: unknown;
+
+  constructor(mapName: string | Mapping, topLevelKey: unknown, secondLevelKey: unknown) {
+    this.mapName = mapName;
+    this.topLevelKey = topLevelKey;
+    this.secondLevelKey = secondLevelKey;
+  }
+
+  toJSON(): { "Fn::FindInMap": [string, unknown, unknown] } {
+    const name = isMapping(this.mapName) ? mappingName(this.mapName) : (this.mapName as string);
+    return {
+      "Fn::FindInMap": [name, resolveIntrinsicValue(this.topLevelKey), resolveIntrinsicValue(this.secondLevelKey)],
+    };
+  }
+}
+
+/**
+ * Create a FindInMap intrinsic. The mapping is the `Mapping` declarable, or
+ * its name. Either key may be a literal or a value intrinsic
+ * (`FindInMap(regionMap, AWS.Region, "AMI")`).
+ */
+export function FindInMap(mapName: string | Mapping, topLevelKey: unknown, secondLevelKey: unknown): FindInMapIntrinsic {
+  return new FindInMapIntrinsic(mapName, topLevelKey, secondLevelKey);
+}
+
+/**
+ * Fn::ImportValue intrinsic function
+ * Reads a value another stack exports.
+ */
+export class ImportValueIntrinsic implements Intrinsic {
+  readonly [INTRINSIC_MARKER] = true as const;
+  private sharedValue: unknown;
+
+  constructor(sharedValue: unknown) {
+    this.sharedValue = sharedValue;
+  }
+
+  toJSON(): { "Fn::ImportValue": unknown } {
+    return { "Fn::ImportValue": resolveIntrinsicValue(this.sharedValue) };
+  }
+}
+
+/** Create an ImportValue intrinsic. The export name is a string or a value intrinsic (`Sub`). */
+export function ImportValue(sharedValue: unknown): ImportValueIntrinsic {
+  return new ImportValueIntrinsic(sharedValue);
+}
+
+/**
+ * Fn::Cidr intrinsic function
+ * Splits an address block into `count` CIDR blocks of `cidrBits` host bits.
+ */
+export class CidrIntrinsic implements Intrinsic {
+  readonly [INTRINSIC_MARKER] = true as const;
+  private ipBlock: unknown;
+  private count: unknown;
+  private cidrBits: unknown;
+
+  constructor(ipBlock: unknown, count: unknown, cidrBits: unknown) {
+    this.ipBlock = ipBlock;
+    this.count = count;
+    this.cidrBits = cidrBits;
+  }
+
+  toJSON(): { "Fn::Cidr": [unknown, unknown, unknown] } {
+    return {
+      "Fn::Cidr": [resolveIntrinsicValue(this.ipBlock), resolveIntrinsicValue(this.count), resolveIntrinsicValue(this.cidrBits)],
+    };
+  }
+}
+
+/** Create a Cidr intrinsic. Each argument is a literal or a value intrinsic, written as the template writes it. */
+export function Cidr(ipBlock: unknown, count: unknown, cidrBits: unknown): CidrIntrinsic {
+  return new CidrIntrinsic(ipBlock, count, cidrBits);
+}

package/src/lint/post-synth/cf-refs.ts

@@ -209,6 +209,16 @@ export function ipv4CidrContains(outer: string, inner: string): boolean | null {
   return iStart >= oStart && iEnd <= oEnd;
 }
 
+/**
+ * A port as a number. CloudFormation accepts `"80"` as well as `80`, so a
+ * string of digits counts; anything else reads as -1, which means all ports.
+ */
+function portNumber(port: unknown): number {
+  if (typeof port === "number") return port;
+  if (typeof port === "string" && /^-?\d+$/.test(port.trim())) return Number(port);
+  return -1;
+}
+
 /**
  * Check if a port range [fromPort, toPort] contains any of the sensitive ports.
  */
@@ -220,8 +230,8 @@ export function portRangeContainsSensitive(
   // Missing ports means all ports
   if (fromPort === undefined && toPort === undefined) return true;
 
-  const from = typeof fromPort === "number" ? fromPort : -1;
-  const to = typeof toPort === "number" ? toPort : -1;
+  const from = portNumber(fromPort);
+  const to = portNumber(toPort);
 
   // If either is an intrinsic, we can't statically verify
   if (isIntrinsic(fromPort) || isIntrinsic(toPort)) return false;

package/src/lint/post-synth/waw019.test.ts

@@ -31,6 +31,38 @@ describe("WAW019: Security Group Unrestricted Ingress", () => {
     expect(diags[0].severity).toBe("error");
   });
 
+  test("ports written as strings are read as numbers", () => {
+    // CloudFormation accepts FromPort: "80"; port 80 is not sensitive.
+    const ctx = makeCtx({
+      Resources: {
+        MySG: {
+          Type: "AWS::EC2::SecurityGroup",
+          Properties: {
+            SecurityGroupIngress: [
+              { IpProtocol: "tcp", FromPort: "80", ToPort: "80", CidrIp: "0.0.0.0/0" },
+              { IpProtocol: "tcp", FromPort: "22", ToPort: "22", CidrIp: "10.0.0.0/8" },
+            ],
+          },
+        },
+      },
+    });
+    expect(checkUnrestrictedIngress(ctx)).toHaveLength(0);
+  });
+
+  test("a sensitive port written as a string is still flagged", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MySG: {
+          Type: "AWS::EC2::SecurityGroup",
+          Properties: {
+            SecurityGroupIngress: [{ IpProtocol: "tcp", FromPort: "22", ToPort: "22", CidrIp: "0.0.0.0/0" }],
+          },
+        },
+      },
+    });
+    expect(checkUnrestrictedIngress(ctx)).toHaveLength(1);
+  });
+
   test("flags SG with ::/0 on port 3389", () => {
     const ctx = makeCtx({
       Resources: {

package/src/lint/post-synth/waw042.test.ts

@@ -117,6 +117,34 @@ describe("WAW042: S3 Bucket Missing TLS-Only Policy", () => {
     expect(checkS3TlsOnlyPolicy(ctx)).toHaveLength(1);
   });
 
+  test("no diagnostic when the BucketPolicy names the bucket with the same Fn::Sub as its BucketName", () => {
+    const name = { "Fn::Sub": "${AppName}-${AWS::Region}-${AWS::AccountId}" };
+    const ctx = makeCtx({
+      Resources: {
+        MyBucket: { Type: "AWS::S3::Bucket", Properties: { BucketName: name } },
+        MyBucketPolicy: {
+          Type: "AWS::S3::BucketPolicy",
+          Properties: { Bucket: name, PolicyDocument: { Statement: [secureTransportDeny] } },
+        },
+      },
+    });
+    expect(checkS3TlsOnlyPolicy(ctx)).toHaveLength(0);
+  });
+
+  test("a policy naming a different bucket by Fn::Sub does not clear this one", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyBucket: { Type: "AWS::S3::Bucket", Properties: { BucketName: { "Fn::Sub": "${AppName}-data" } } },
+        MyBucketPolicy: {
+          Type: "AWS::S3::BucketPolicy",
+          Properties: { Bucket: { "Fn::Sub": "${AppName}-logs" }, PolicyDocument: { Statement: [secureTransportDeny] } },
+        },
+      },
+    });
+    const diags = checkS3TlsOnlyPolicy(ctx);
+    expect(diags.map((d) => d.entity)).toEqual(["MyBucket"]);
+  });
+
   test("a policy covering a different bucket does not clear this one", () => {
     const ctx = makeCtx({
       Resources: {

package/src/lint/post-synth/waw042.ts

@@ -26,10 +26,31 @@ function statementDeniesInsecureTransport(stmt: Record<string, unknown>): boolea
   return false;
 }
 
-/** Logical ids of every bucket a BucketPolicy's `Bucket` property resolves to. */
-function bucketPolicyTargets(resource: CFResource): Set<string> {
+/** A value as JSON with its object keys sorted, for comparing two values. */
+function canonical(value: unknown): string {
+  return JSON.stringify(value, (_key, v) =>
+    v && typeof v === "object" && !Array.isArray(v)
+      ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, (v as Record<string, unknown>)[k]]))
+      : v,
+  );
+}
+
+/**
+ * Logical ids of every bucket a BucketPolicy's `Bucket` property resolves to:
+ * a bucket it references (`Ref`, `GetAtt`), or a bucket whose `BucketName`
+ * is the same value (`Fn::Sub: "${AppName}-${AWS::Region}"` on both).
+ */
+function bucketPolicyTargets(resource: CFResource, resources: Record<string, CFResource>): Set<string> {
   const props = resource.Properties ?? {};
-  return findResourceRefs(props.Bucket);
+  const targets = findResourceRefs(props.Bucket);
+  if (props.Bucket === undefined) return targets;
+  const policyBucket = canonical(props.Bucket);
+  for (const [logicalId, other] of Object.entries(resources)) {
+    if (other.Type !== "AWS::S3::Bucket") continue;
+    const name = other.Properties?.BucketName;
+    if (name !== undefined && canonical(name) === policyBucket) targets.add(logicalId);
+  }
+  return targets;
 }
 
 export function checkS3TlsOnlyPolicy(ctx: PostSynthContext): PostSynthDiagnostic[] {
@@ -55,7 +76,7 @@ export function checkS3TlsOnlyPolicy(ctx: PostSynthContext): PostSynthDiagnostic
       );
       if (!hasTlsDeny) continue;
 
-      for (const bucketId of bucketPolicyTargets(resource)) {
+      for (const bucketId of bucketPolicyTargets(resource, template.Resources)) {
         bucketsWithTlsPolicy.add(bucketId);
       }
     }

package/src/mapping.test.ts

@@ -0,0 +1,64 @@
+import { describe, test, expect } from "vitest";
+import { Mapping, isMapping, MAPPING_ENTITY_TYPE } from "./mapping";
+import { FindInMap, Ref } from "./intrinsics";
+import { AWS } from "./pseudo";
+import { Parameter } from "./parameter";
+import { awsSerializer } from "./serializer";
+import { createResource } from "@intentius/chant/runtime";
+import { resolveAttrRefs } from "@intentius/chant/discovery/resolve";
+import type { Declarable } from "@intentius/chant/declarable";
+
+const Subnet = createResource("AWS::EC2::Subnet", "aws", {});
+
+function serialize(entities: Map<string, Declarable>): Record<string, any> {
+  resolveAttrRefs(entities);
+  return JSON.parse(awsSerializer.serialize(entities) as string);
+}
+
+describe("Mapping and FindInMap", () => {
+  test("a Mapping is lifted into Mappings and FindInMap reads it by name", () => {
+    const regionMap = new Mapping({ "us-east-1": { AZs: ["us-east-1a", "us-east-1b"] } });
+    const env = new Parameter("String");
+    const subnet = new Subnet({
+      AvailabilityZone: FindInMap(regionMap, AWS.Region, "AZs"),
+      Tag: FindInMap("Other", Ref(env), "Key"),
+    });
+    const template = serialize(
+      new Map<string, Declarable>([
+        ["RegionMap", regionMap],
+        ["Env", env],
+        ["Subnet", subnet],
+      ]),
+    );
+    expect(template.Mappings).toEqual({ RegionMap: { "us-east-1": { AZs: ["us-east-1a", "us-east-1b"] } } });
+    expect(template.Resources.Subnet.Properties.AvailabilityZone).toEqual({
+      "Fn::FindInMap": ["RegionMap", { Ref: "AWS::Region" }, "AZs"],
+    });
+    expect(template.Resources.Subnet.Properties.Tag).toEqual({ "Fn::FindInMap": ["Other", { Ref: "Env" }, "Key"] });
+  });
+
+  test("a Mapping's name option is its key in Mappings and in FindInMap", () => {
+    const map = new Mapping({ a: { b: "c" } }, { name: "Shared" });
+    const subnet = new Subnet({ Tag: FindInMap(map, "a", "b") });
+    const template = serialize(new Map<string, Declarable>([["SharedMapping", map], ["Subnet", subnet]]));
+    expect(Object.keys(template.Mappings)).toEqual(["Shared"]);
+    expect(template.Resources.Subnet.Properties.Tag).toEqual({ "Fn::FindInMap": ["Shared", "a", "b"] });
+  });
+
+  test("isMapping and the entity type", () => {
+    const map = new Mapping({});
+    expect(map.entityType).toBe(MAPPING_ENTITY_TYPE);
+    expect(isMapping(map)).toBe(true);
+    expect(isMapping(new Parameter("String"))).toBe(false);
+    expect(() => new Mapping([] as never)).toThrow(/map must be an object/);
+  });
+});
+
+describe("an import envelope in the template", () => {
+  test("fails the build instead of being written as CloudFormation", () => {
+    const subnet = new Subnet({ AvailabilityZone: { __intrinsic: "FindInMap", mapName: "RegionMap", firstKey: "a", secondKey: "b" } });
+    expect(() => serialize(new Map<string, Declarable>([["Subnet", subnet]]))).toThrow(
+      /Resources\.Subnet\.Properties\.AvailabilityZone: \{ __intrinsic: "FindInMap" \} is an import envelope/,
+    );
+  });
+});

package/src/mapping.ts

@@ -0,0 +1,41 @@
+/**
+ * CloudFormation template mapping.
+ *
+ * A `Mapping` declarable is lifted into the template's `Mappings` section by
+ * the serializer, the way `Condition` is lifted into `Conditions`. Read a
+ * value from it with `FindInMap(mapping, topLevelKey, secondLevelKey)`.
+ */
+
+import { DECLARABLE_MARKER, isDeclarable, type Declarable } from "@intentius/chant/declarable";
+import { getLogicalName } from "@intentius/chant/utils";
+
+export const MAPPING_ENTITY_TYPE = "AWS::CloudFormation::Mapping";
+
+export class Mapping implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "aws";
+  readonly entityType = MAPPING_ENTITY_TYPE;
+  /** Top-level key -> second-level key -> value. */
+  readonly map: Record<string, Record<string, unknown>>;
+  /** The mapping's key in the template's `Mappings`, when it is not the
+   * export name. */
+  readonly name?: string;
+
+  constructor(map: Record<string, Record<string, unknown>>, options?: { name?: string }) {
+    if (typeof map !== "object" || map === null || Array.isArray(map)) {
+      throw new Error("new Mapping(map): map must be an object of top-level keys to objects of second-level keys");
+    }
+    this.map = map;
+    if (options?.name !== undefined) this.name = options.name;
+  }
+}
+
+/** Type guard for the `Mapping` declarable, duck-typed on `entityType` (#1137). */
+export function isMapping(value: unknown): value is Mapping {
+  return isDeclarable(value) && value.entityType === MAPPING_ENTITY_TYPE;
+}
+
+/** The name a mapping has in the template: its `name` option, else its logical name. */
+export function mappingName(mapping: Mapping): string {
+  return mapping.name ?? getLogicalName(mapping);
+}

package/src/parameter.ts

@@ -1,5 +1,20 @@
 import { DECLARABLE_MARKER, type CoreParameter } from "@intentius/chant/declarable";
 
+/**
+ * What CloudFormation checks a parameter value against. Numeric bounds are
+ * kept as written: templates write `MinLength: "1"` as often as `1`.
+ */
+export interface ParameterConstraints {
+  allowedValues?: unknown[];
+  allowedPattern?: string;
+  constraintDescription?: string;
+  minLength?: number | string;
+  maxLength?: number | string;
+  minValue?: number | string;
+  maxValue?: number | string;
+  noEcho?: boolean | string;
+}
+
 export class Parameter implements CoreParameter {
   readonly [DECLARABLE_MARKER] = true as const;
   readonly lexicon = "aws";
@@ -7,10 +22,16 @@ export class Parameter implements CoreParameter {
   readonly parameterType: string;
   readonly description?: string;
   readonly defaultValue?: unknown;
+  readonly constraints?: ParameterConstraints;
 
-  constructor(type: string, options?: { description?: string; defaultValue?: unknown }) {
+  constructor(type: string, options?: { description?: string; defaultValue?: unknown } & ParameterConstraints) {
     this.parameterType = type;
     this.description = options?.description;
     this.defaultValue = options?.defaultValue;
+    if (options) {
+      const { description: _d, defaultValue: _v, ...constraints } = options;
+      const set = Object.entries(constraints).filter(([, v]) => v !== undefined);
+      if (set.length > 0) this.constraints = Object.fromEntries(set) as ParameterConstraints;
+    }
   }
 }

package/src/plugin.test.ts

@@ -48,7 +48,7 @@ describe("awsPlugin", () => {
 
   test("returns intrinsics", () => {
     const intrinsics = awsPlugin.intrinsics!();
-    expect(intrinsics.length).toBe(13);
+    expect(intrinsics.length).toBe(16);
     const names = intrinsics.map((i) => i.name);
     expect(names).toContain("Sub");
     expect(names).toContain("Ref");
@@ -57,6 +57,7 @@ describe("awsPlugin", () => {
     expect(names).toContain("And");
     expect(names).toContain("Or");
     expect(names).toContain("Not");
+    expect(names).toContain("FindInMap");
   });
 
   test("returns pseudo-parameters", () => {

package/src/plugin.ts

@@ -118,6 +118,9 @@ export const awsPlugin: LexiconPlugin = {
       { name: "And", description: "Fn::And — condition conjunction", isTag: false, foldsAsCall: true },
       { name: "Or", description: "Fn::Or — condition disjunction", isTag: false, foldsAsCall: true },
       { name: "Not", description: "Fn::Not — condition negation", isTag: false, foldsAsCall: true },
+      { name: "FindInMap", description: "Fn::FindInMap — value from a declared mapping", isTag: false, foldsAsCall: true },
+      { name: "ImportValue", description: "Fn::ImportValue — value another stack exports", isTag: false, foldsAsCall: true },
+      { name: "Cidr", description: "Fn::Cidr — CIDR blocks from an address block", isTag: false, foldsAsCall: true },
     ];
   },
 

package/src/serializer.ts

@@ -19,11 +19,13 @@ import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
 import { isChildProject, type ChildProjectInstance } from "@intentius/chant/child-project";
 import { isStackOutput, type StackOutput } from "@intentius/chant/stack-output";
-import { isAttrRefLike, getLogicalName } from "@intentius/chant/utils";
+import { isAttrRefLike } from "@intentius/chant/utils";
 import { resolveDependsOn } from "@intentius/chant/resource-attributes";
-import { isCondition } from "./condition";
+import { conditionName, isCondition } from "./condition";
+import { isMapping } from "./mapping";
 import { isDefaultTags, type TagEntry } from "./default-tags";
 import { isTemplateTransform } from "./template-transform";
+import { isTemplateSection } from "./template-sections";
 import { loadTaggableResources } from "./taggable";
 
 /**
@@ -42,6 +44,7 @@ interface CFTemplate {
   Metadata?: Record<string, unknown>;
   Transform?: string | string[];
   Parameters?: Record<string, CFParameter>;
+  Mappings?: Record<string, unknown>;
   Conditions?: Record<string, unknown>;
   Resources: Record<string, CFResource>;
   Outputs?: Record<string, CFOutput>;
@@ -57,13 +60,25 @@ interface CFParameter {
   AllowedValues?: unknown[];
   AllowedPattern?: string;
   ConstraintDescription?: string;
-  MaxLength?: number;
-  MaxValue?: number;
-  MinLength?: number;
-  MinValue?: number;
-  NoEcho?: boolean;
+  MaxLength?: number | string;
+  MaxValue?: number | string;
+  MinLength?: number | string;
+  MinValue?: number | string;
+  NoEcho?: boolean | string;
 }
 
+/** Parameter constraint options and the CloudFormation keys they emit as. */
+const PARAMETER_CONSTRAINT_KEYS = [
+  ["allowedValues", "AllowedValues"],
+  ["allowedPattern", "AllowedPattern"],
+  ["constraintDescription", "ConstraintDescription"],
+  ["minLength", "MinLength"],
+  ["maxLength", "MaxLength"],
+  ["minValue", "MinValue"],
+  ["maxValue", "MaxValue"],
+  ["noEcho", "NoEcho"],
+] as const;
+
 /**
  * CloudFormation resource
  */
@@ -314,6 +329,22 @@ function serializeToTemplate(
     template.Transform = transforms;
   }
 
+  // Template-level Description and Metadata declarations. Declared Metadata
+  // keys come first; the ownership marker and receipt rows written above are
+  // chant's own and win on a key collision.
+  const declaredMetadata: Record<string, unknown> = {};
+  for (const [, entity] of entities) {
+    if (!isTemplateSection(entity)) continue;
+    if (entity.section === "Description") {
+      template.Description = entity.value as string;
+    } else {
+      Object.assign(declaredMetadata, toCFValue(entity.value, entityNames) as Record<string, unknown>);
+    }
+  }
+  if (Object.keys(declaredMetadata).length > 0) {
+    template.Metadata = { ...declaredMetadata, ...(template.Metadata ?? {}) };
+  }
+
   // Process entities
   for (const [name, entity] of entities) {
     // Skip StackOutput entities — they go in the Outputs section
@@ -327,7 +358,7 @@ function serializeToTemplate(
     }
 
     // Skip TemplateTransform entities — lifted to the top-level Transform above
-    if (isTemplateTransform(entity)) {
+    if (isTemplateTransform(entity) || isTemplateSection(entity)) {
       continue;
     }
 
@@ -348,14 +379,27 @@ function serializeToTemplate(
         param.Default = entity.defaultValue;
       }
 
+      const constraints = (entity as { constraints?: Record<string, unknown> }).constraints;
+      if (constraints) {
+        for (const [option, key] of PARAMETER_CONSTRAINT_KEYS) {
+          if (constraints[option] !== undefined) (param as unknown as Record<string, unknown>)[key] = constraints[option];
+        }
+      }
+
       template.Parameters[name] = param;
+    } else if (isMapping(entity)) {
+      // Mapping declarable -> Mappings section, read with FindInMap.
+      if (!template.Mappings) {
+        template.Mappings = {};
+      }
+      template.Mappings[entity.name ?? name] = toCFValue(entity.map, entityNames);
     } else if (isCondition(entity)) {
       // Condition declarable → Conditions section (#2068), lifted the way
       // Parameter is lifted into Parameters above.
       if (!template.Conditions) {
         template.Conditions = {};
       }
-      template.Conditions[name] = toCFValue(entity.expression, entityNames);
+      template.Conditions[entity.name ?? name] = toCFValue(entity.expression, entityNames);
     } else if (isChildProject(entity)) {
       // ChildProjectInstance → AWS::CloudFormation::Stack resource
       const childProject = entity as ChildProjectInstance;
@@ -409,7 +453,7 @@ function serializeToTemplate(
         // as well as a name string (#2068).
         if (attrs.Condition) {
           resource.Condition = isCondition(attrs.Condition)
-            ? entityNames.get(attrs.Condition) ?? getLogicalName(attrs.Condition)
+            ? conditionName(attrs.Condition, entityNames)
             : attrs.Condition as string;
         }
         if (attrs.DeletionPolicy) resource.DeletionPolicy = attrs.DeletionPolicy as string;
@@ -489,10 +533,11 @@ function serializeToTemplate(
       const condition = (stackOutput as { condition?: unknown }).condition;
       if (condition) {
         output.Condition = isCondition(condition)
-          ? entityNames.get(condition) ?? getLogicalName(condition)
+          ? conditionName(condition, entityNames)
           : condition as string;
       }
-      template.Outputs[name] = output;
+      // Read defensively, like exportName: the name option postdates older cores.
+      template.Outputs[(stackOutput as { name?: string }).name ?? name] = output;
     }
   }
 
@@ -515,9 +560,31 @@ function serializeToTemplate(
     template.Outputs = { ...template.Outputs, ...extraOutputs };
   }
 
+  refuseImportEnvelopes(template);
   return template;
 }
 
+/**
+ * Throw on an import IR envelope (`{ "__intrinsic": "FindInMap", ... }`) in
+ * the synthesized template. It is not CloudFormation, and a build that wrote
+ * one used to exit 0 with a template CloudFormation rejects.
+ */
+function refuseImportEnvelopes(value: unknown, path: string[] = []): void {
+  if (value === null || typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    value.forEach((item, i) => refuseImportEnvelopes(item, [...path, String(i)]));
+    return;
+  }
+  const obj = value as Record<string, unknown>;
+  if (typeof obj.__intrinsic === "string") {
+    throw new Error(
+      `${path.join(".")}: { __intrinsic: "${obj.__intrinsic}" } is an import envelope, not CloudFormation; ` +
+        `write the ${obj.__intrinsic} intrinsic instead`,
+    );
+  }
+  for (const [key, v] of Object.entries(obj)) refuseImportEnvelopes(v, [...path, key]);
+}
+
 /**
  * AWS CloudFormation serializer implementation
  */