fix(aws): allow the scoped SAM transform (#185)

## Summary

- let the CloudFormation service role call
`cloudformation:CreateChangeSet` only on the regional AWS-owned
`Serverless-2016-10-31` transform
- keep arbitrary CloudFormation stacks and change sets outside the
service role
- add policy-conformance coverage and document the trust boundary

## Evidence

A real least-privilege deployment from `HayaSendDeploymentOperatorTest`
reached SAM change-set creation but CloudFormation rejected its own
service-role session on the transform ARN. AWS documents this exact
resource-level permission pattern:
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/control-access-with-iam.html

The failed stack remained `REVIEW_IN_PROGRESS` with no application
resources. It was deleted through the restricted operator role, and all
seven exact-prefix artifact versions were purged; the stack and prefix
are absent.

## Validation

- `npm run check`
- `npm test -- --run` — 629 passed, 6 skipped
- SAM lint passed
- live CloudFormation template validation passed in account
`330599756148`, `ap-northeast-1`
- GPG-signed commit `aab278aa9d822dfc7eb6f2666551f6d34b95d4ee`

This advances #174 but does not mark its least-privilege or lifecycle
proof complete until an exact-main rerun succeeds.

Author: yhay81

deploy/aws-cloudformation-bootstrap.yaml

@@ -99,6 +99,10 @@ Resources:
           PolicyDocument:
             Version: "2012-10-17"
             Statement:
+              - Sid: UseOnlyTheSAMTransform
+                Effect: Allow
+                Action: cloudformation:CreateChangeSet
+                Resource: !Sub "arn:${AWS::Partition}:cloudformation:${AWS::Region}:aws:transform/Serverless-2016-10-31"
               - Effect: Allow
                 Action:
                   - iam:AttachRolePolicy

docs/aws-quickstart.md

@@ -39,6 +39,8 @@ policy. The operator policy can manage only HayaSend stack names under the
 selected prefix, that artifact path, and `iam:PassRole` for the exact service
 role. It does not grant the operator Lambda, DynamoDB, SES, backup, or other
 application data-plane provisioning permissions.
+The service role may invoke the regional AWS-owned SAM transform, but it
+cannot create arbitrary CloudFormation stacks or change sets.
 
 Apply from a one-time IAM bootstrap session only after reviewing the template:
 

docs/operations.md

@@ -62,12 +62,15 @@ retained-resource and stack-deletion controls.
 The checked-in bootstrap policy is action-scoped to the AWS services generated
 by `template.yaml`; it is not AdministratorAccess. IAM role creation and
 passing are restricted to the application stack prefix and approved AWS
-services. Some other CloudFormation service actions still require
-`Resource: "*"`, especially create-time Lambda, API Gateway, backup, KMS, and
-SES operations whose final ARN does not yet exist. Treat the optional
-organizational permissions boundary and SCPs as the outer guardrail. CI
-rejects a newly introduced application resource type until its required
-service prefix is reviewed in the bootstrap-policy conformance test.
+services. The service role may call `cloudformation:CreateChangeSet` only on
+the regional AWS-owned `Serverless-2016-10-31` transform required to expand
+the SAM template; it cannot create arbitrary CloudFormation stacks or change
+sets. Some other CloudFormation service actions still require `Resource: "*"`,
+especially create-time Lambda, API Gateway, backup, KMS, and SES operations
+whose final ARN does not yet exist. Treat the optional organizational
+permissions boundary and SCPs as the outer guardrail. CI rejects a newly
+introduced application resource type until its required service prefix is
+reviewed in the bootstrap-policy conformance test.
 
 `cleanup aws --apply` needs `cloudformation:DeleteStack` and, for the normal
 protected stack, `cloudformation:UpdateTerminationProtection` in addition to

tests/aws-cloudformation-bootstrap-template.test.ts

@@ -101,6 +101,16 @@ describe("AWS CloudFormation deployment bootstrap template", () => {
       bootstrap.indexOf("  CloudFormationServiceRole:"),
       bootstrap.indexOf("\n  OperatorPolicy:"),
     );
+    expect(serviceRoleSection).toContain("Sid: UseOnlyTheSAMTransform");
+    expect(serviceRoleSection).toContain(
+      "Action: cloudformation:CreateChangeSet",
+    );
+    expect(serviceRoleSection).toContain(
+      'Resource: !Sub "arn:${AWS::Partition}:cloudformation:${AWS::Region}:aws:transform/Serverless-2016-10-31"',
+    );
+    expect(serviceRoleSection).not.toContain(
+      "arn:${AWS::Partition}:cloudformation:${AWS::Region}:aws:transform/*",
+    );
     expect(serviceRoleSection).toContain(
       'Resource: !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/${ApplicationStackNamePrefix}*"',
     );