feat(iam): add feature flag to validate PolicyStatement SID is alphanumeric

[camerondurham]

Resolves #34819 by throwing error when PolicyStatement Statement id contains characters not allowed by the API.

Note this does duplicate #34828. I realized that PR makes too many changes to existing integ tests. This change is intended to be less intrusive.

Reference: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_sid.html

The Sid element supports ASCII uppercase letters (A-Z), lowercase letters (a-z), and numbers (0-9).

Issue # (if applicable)

Closes #34819

Reason for this change

CDK build allows users to write invalid statement ids containing dashes when building policy statements, then failed on deployment. To reduce time to a successful deployment, I believe the CDK should throw an exception at build time to help user make a fix locally before a failed deployment.

Description of changes

Validate that statement id matches requirements specified in https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_sid.html in the constructor.

Add tests that verify only valid statement ids are set in constructor.

Describe any new or updated permissions being added

n/a

Description of how you validated changes

yes, added unit tests

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[aws-cdk-automation]

(This review is outdated)

[camerondurham]

Will fix later today after work.

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

[github-actions]

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
This security report is NOT a review blocker. Please try merge from main to avoid findings unrelated to the PR.
To suppress a specific rule, see Suppressing Rules.

---

	Tests	Passed ✅	Skipped	Failed
Security Guardian Results	48 ran	48 passed

Test	Result
No test annotations available

• View Security Guardian Results

[github-actions]

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
This security report is NOT a review blocker. Please try merge from main to avoid findings unrelated to the PR.
To suppress a specific rule, see Suppressing Rules.

---

	Tests	Passed ✅	Skipped	Failed
Security Guardian Results with resolved templates	48 ran	48 passed

Test	Result
No test annotations available

• View Security Guardian Results with resolved templates

Pull request has been modified.

Pull request has been modified.

Pull request has been modified.

[alvazjor]

Thanks for working on this @camerondurham — catching invalid SIDs at synth time instead of deploy time is a real improvement. I have a suggestion that would simplify this PR significantly by removing the need for a feature flag entirely.

The issue I see with the current approach

The validation currently lives in PolicyDocument.resolve(), which fires for every policy document — identity policies, resource policies, key policies, topic policies, etc. The problem is that the [0-9A-Za-z]* rule is specific to IAM identity policies. Other services have documented broader SID rules:

• KMS explicitly documents that key policy SIDs can include spaces: "The Sid element in a key policy statement can include spaces. (Spaces are prohibited in the Sid element of an IAM policy document.)"
• SNS requires unique SIDs but documents no character restriction.
• S3, SQS, Lambda — no documented SID character restriction.

I suspect the feature flag was introduced because applying the validation universally would break resource policies that legitimately use broader SID characters (your prior PR #34828 had to modify existing integ tests for this reason, if I'm reading the history correctly). If that's the case, there's a simpler path that avoids the flag altogether.

Proposed alternative: move validation to validateForIdentityPolicy()

CDK already has the infrastructure to distinguish identity policies from resource policies:

• PolicyStatement.validateForIdentityPolicy() is called from Policy (inline policies) and ManagedPolicy during synth via node.addValidation()
• PolicyStatement.validateForResourcePolicy() is called separately for resource policies

If you move the SID check into validateForIdentityPolicy(), it only fires where IAM actually enforces the rule. Non-alphanumeric SIDs in identity policies always fail at deploy time (IAM returns a 400), so this becomes a straight bug fix — no feature flag needed per our contribution guidelines:

Input that was accepted by synth but always failed at deploy time → feature flag NOT required; fail-fast synth-time validation is preferred.

The change would look like this in policy-statement.ts:

public validateForIdentityPolicy(): string[] {
  const errors = this.validateForAnyPolicy();
  // ... existing checks ...

  // IAM strictly enforces alphanumeric SIDs for identity policies
  if (this._sid !== undefined && !cdk.Token.isUnresolved(this._sid) && !/^[0-9A-Za-z]*$/.test(this._sid)) {
    errors.push(
      `Statement ID (sid) '${this._sid}' must be alphanumeric (A-Z, a-z, 0-9) when used in an identity-based policy. See https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_sid.html`,
    );
  }
  return errors;
}

What this eliminates

• The feature flag definition in cx-api/lib/features.ts
• The exported constant (IAM_POLICY_STATEMENT_VALIDATE_SID)
• The _validateSid() method
• The flag check in PolicyDocument.resolve()
• All changes to FEATURE_FLAGS.md and recommended-feature-flags.json
• The flag context in the integ test

Summary

The bug is real, the fix is welcome, but if it is possible to be scoped to where the rule actually applies, we wont need a feature flag at all. Happy to answer questions if anything is unclear.

[camerondurham]

Great point @alvazjor , that's my bad I missed the SID restriction didn't apply to every type of policy document just the IAM ones.

I've moved SID validation to a dedicated function and removed the feature flag. I ran builds / new integ and framework tests but was not able to completely run deploy-mode on changes.

This PR should now just be scoped to IAM Identity policies only and the feature flag behavior removed.

Let me know if there's any additional feedback, thank you!

[camerondurham]

This URL may change in the future and this would immediately become stale. Should this be removed? Are agents / llms good enough to look up and use latest AWS docs automatically so this is irreleant?