Introduce IPolicyStatement

PolicyStatement is no longer IResolvable (doesn't need to be)

Remove AwsPrincipal, which was always an alias for ArnPrincipal
which is much clearer.

Introduce `PolicyStatement.fromAttributes({ ... })` as an
alternative to the fluent interface chaining of old `PolicyStatement`.

packages/@aws-cdk/aws-iam/README.md

@@ -71,7 +71,7 @@ If multiple principals are added to the policy statement, they will be merged to
 const statement = new PolicyStatement();
 statement.addServicePrincipal('cloudwatch.amazonaws.com');
 statement.addServicePrincipal('ec2.amazonaws.com');
-statement.addAwsPrincipal('arn:aws:boom:boom');
+statement.addArnPrincipal('arn:aws:boom:boom');
 ```
 
 Will result in:

packages/@aws-cdk/aws-iam/lib/policy-document.ts

@@ -1,6 +1,6 @@
 import cdk = require('@aws-cdk/cdk');
 import { IPostProcessor } from '@aws-cdk/cdk';
-import { PolicyStatement } from './policy-statement';
+import { IPolicyStatement } from './policy-statement';
 
 /**
  * Properties for a new PolicyDocument
@@ -18,7 +18,7 @@ export interface PolicyDocumentProps {
  * A PolicyDocument is a collection of statements
  */
 export class PolicyDocument implements cdk.IResolvable {
-  private readonly statements = new Array<PolicyStatement>();
+  private readonly statements = new Array<IPolicyStatement>();
   private readonly autoAssignSids: boolean;
 
   constructor(props: PolicyDocumentProps = {}) {
@@ -47,7 +47,7 @@ export class PolicyDocument implements cdk.IResolvable {
    *
    * @param statement the statement to add.
    */
-  public addStatements(...statement: PolicyStatement[]) {
+  public addStatements(...statement: IPolicyStatement[]) {
     this.statements.push(...statement);
   }
 
@@ -60,13 +60,22 @@ export class PolicyDocument implements cdk.IResolvable {
     });
   }
 
+  /**
+   * JSON-ify the document
+   *
+   * Used when JSON.stringify() is called
+   */
+  public toJSON() {
+    return this.render();
+  }
+
   private render(): any {
     if (this.isEmpty) {
       return undefined;
     }
 
     const doc = {
-      Statement: this.statements,
+      Statement: this.statements.map(s => s.toStatementJson()),
       Version: '2012-10-17'
     };
 

packages/@aws-cdk/aws-iam/lib/policy-statement.ts

@@ -3,10 +3,34 @@ import { AccountPrincipal, AccountRootPrincipal, Anyone, ArnPrincipal, Canonical
   FederatedPrincipal, IPrincipal, ServicePrincipal, ServicePrincipalOpts } from './principals';
 import { mergePrincipal } from './util';
 
+/**
+ * An abstract PolicyStatement
+ */
+export interface IPolicyStatement {
+  /**
+   * Render the policy statement to JSON
+   */
+  toStatementJson(): any;
+}
+
 /**
  * Represents a statement in an IAM policy document.
  */
-export class PolicyStatement implements cdk.IResolvable {
+export class PolicyStatement implements IPolicyStatement {
+  public static fromAttributes(attrs: PolicyStatementAttributes): IPolicyStatement {
+    const st = new PolicyStatement();
+    st.addActions(...attrs.actions || []);
+    (attrs.principals || []).forEach(p => st.addPrincipal(p));
+    st.addResources(...attrs.resourceArns || []);
+    if (attrs.conditions !== undefined) {
+      st.addConditions(attrs.conditions);
+    }
+    return st;
+  }
+
+  /**
+   * Statement ID for this statement
+   */
   public sid?: string;
 
   private action = new Array<any>();
@@ -51,16 +75,12 @@ export class PolicyStatement implements cdk.IResolvable {
     return this;
   }
 
-  public addAwsPrincipal(arn: string): this {
-    return this.addPrincipal(new ArnPrincipal(arn));
-  }
-
   public addAwsAccountPrincipal(accountId: string): this {
     return this.addPrincipal(new AccountPrincipal(accountId));
   }
 
   public addArnPrincipal(arn: string): this {
-    return this.addAwsPrincipal(arn);
+    return this.addPrincipal(new ArnPrincipal(arn));
   }
 
   /**
@@ -180,14 +200,7 @@ export class PolicyStatement implements cdk.IResolvable {
     return this.addCondition('StringEquals', { 'sts:ExternalId': accountId });
   }
 
-  //
-  // Serialization
-  //
-  public resolve(_context: cdk.IResolveContext): any {
-    return this.toJson();
-  }
-
-  public toJson(): any {
+  public toStatementJson(): any {
     return {
       Action: _norm(this.action),
       Condition: _norm(this.condition),
@@ -251,12 +264,50 @@ export class PolicyStatement implements cdk.IResolvable {
     });
   }
 
+  /**
+   * JSON-ify the statement
+   *
+   * Used when JSON.stringify() is called
+   */
   public toJSON() {
-    return this.toJson();
+    return this.toStatementJson();
   }
 }
 
 export enum PolicyStatementEffect {
   Allow = 'Allow',
   Deny = 'Deny',
+}
+
+/**
+ * Interface for creating a policy statement
+ */
+export interface PolicyStatementAttributes {
+  /**
+   * List of actions to add to the statement
+   *
+   * @default - no actions
+   */
+  actions?: string[];
+
+  /**
+   * List of principals to add to the statement
+   *
+   * @default - no principals
+   */
+  principals?: IPrincipal[];
+
+  /**
+   * Resource ARNs to add to the statement
+   *
+   * @default - no principals
+   */
+  resourceArns?: string[];
+
+  /**
+   * Conditions to add to the statement
+   *
+   * @default - no condition
+   */
+  conditions?: {[key: string]: any};
 }

packages/@aws-cdk/aws-iam/test/test.policy-document.ts

@@ -17,7 +17,7 @@ export = {
     p.addAwsAccountPrincipal(`my${Token.asString({ account: 'account' })}name`);
     p.limitToAccount('12221121221');
 
-    test.deepEqual(stack.resolve(p), { Action:
+    test.deepEqual(stack.resolve(p.toStatementJson()), { Action:
       [ 'sqs:SendMessage',
         'dynamodb:CreateTable',
         'dynamodb:DeleteTable' ],
@@ -63,7 +63,7 @@ export = {
   'Permission allows specifying multiple actions upon construction'(test: Test) {
     const stack = new Stack();
     const perm = new PolicyStatement().addResource('MyResource').addActions('Action1', 'Action2', 'Action3');
-    test.deepEqual(stack.resolve(perm), {
+    test.deepEqual(stack.resolve(perm.toStatementJson()), {
       Effect: 'Allow',
       Action: [ 'Action1', 'Action2', 'Action3' ],
       Resource: 'MyResource' });
@@ -82,7 +82,7 @@ export = {
     const p = new PolicyStatement();
     const canoncialUser = "averysuperduperlongstringfor";
     p.addPrincipal(new CanonicalUserPrincipal(canoncialUser));
-    test.deepEqual(stack.resolve(p), {
+    test.deepEqual(stack.resolve(p.toStatementJson()), {
       Effect: "Allow",
       Principal: {
         CanonicalUser: canoncialUser
@@ -96,7 +96,7 @@ export = {
 
     const p = new PolicyStatement();
     p.addAccountRootPrincipal();
-    test.deepEqual(stack.resolve(p), {
+    test.deepEqual(stack.resolve(p.toStatementJson()), {
       Effect: "Allow",
       Principal: {
         AWS: {
@@ -120,7 +120,7 @@ export = {
     const stack = new Stack();
     const p = new PolicyStatement();
     p.addFederatedPrincipal("com.amazon.cognito", { StringEquals: { key: 'value' }});
-    test.deepEqual(stack.resolve(p), {
+    test.deepEqual(stack.resolve(p.toStatementJson()), {
       Effect: "Allow",
       Principal: {
         Federated: "com.amazon.cognito"
@@ -138,7 +138,7 @@ export = {
     const p = new PolicyStatement();
     p.addAwsAccountPrincipal('1234');
     p.addAwsAccountPrincipal('5678');
-    test.deepEqual(stack.resolve(p), {
+    test.deepEqual(stack.resolve(p.toStatementJson()), {
       Effect: 'Allow',
       Principal: {
         AWS: [
@@ -181,7 +181,7 @@ export = {
 
     'true if there is a principal'(test: Test) {
       const p = new PolicyStatement();
-      p.addAwsPrincipal('bla');
+      p.addArnPrincipal('bla');
       test.equal(p.hasPrincipal, true);
       test.done();
     }
@@ -244,34 +244,14 @@ export = {
     }
   },
 
-  'addAwsPrincipal/addArnPrincipal are the aliases'(test: Test) {
-    const stack = new Stack();
-    const p = new PolicyDocument();
-
-    p.addStatements(new PolicyStatement().addAwsPrincipal('111222-A'));
-    p.addStatements(new PolicyStatement().addArnPrincipal('111222-B'));
-    p.addStatements(new PolicyStatement().addPrincipal(new ArnPrincipal('111222-C')));
-
-    test.deepEqual(stack.resolve(p), {
-      Statement: [ {
-        Effect: 'Allow', Principal: { AWS: '111222-A' } },
-        { Effect: 'Allow', Principal: { AWS: '111222-B' } },
-        { Effect: 'Allow', Principal: { AWS: '111222-C' } }
-      ],
-      Version: '2012-10-17'
-    });
-
-    test.done();
-  },
-
   'addResources() will not break a list-encoded Token'(test: Test) {
     const stack = new Stack();
 
     const statement = new PolicyStatement()
       .addActions(...Lazy.listValue({ produce: () => ['a', 'b', 'c'] }))
       .addResources(...Lazy.listValue({ produce: () => ['x', 'y', 'z'] }));
 
-    test.deepEqual(stack.resolve(statement), {
+    test.deepEqual(stack.resolve(statement.toStatementJson()), {
       Effect: 'Allow',
       Action: ['a', 'b', 'c'],
       Resource: ['x', 'y', 'z'],
@@ -308,7 +288,7 @@ export = {
     };
     const s = new PolicyStatement().addAccountRootPrincipal()
                                    .addPrincipal(arrayPrincipal);
-    test.deepEqual(stack.resolve(s), {
+    test.deepEqual(stack.resolve(s.toStatementJson()), {
       Effect: 'Allow',
       Principal: {
         AWS: [
@@ -324,12 +304,12 @@ export = {
   'policy statements with multiple principal types can be created using multiple addPrincipal calls'(test: Test) {
     const stack = new Stack();
     const s = new PolicyStatement()
-      .addAwsPrincipal('349494949494')
+      .addArnPrincipal('349494949494')
       .addServicePrincipal('test.service')
       .addResource('resource')
       .addAction('action');
 
-    test.deepEqual(stack.resolve(s), {
+    test.deepEqual(stack.resolve(s.toStatementJson()), {
       Action: 'action',
       Effect: 'Allow',
       Principal: { AWS: '349494949494', Service: 'test.service' },
@@ -346,7 +326,7 @@ export = {
         .addAction('test:Action')
         .addServicePrincipal('codedeploy.amazonaws.com');
 
-      test.deepEqual(stack.resolve(s), {
+      test.deepEqual(stack.resolve(s.toStatementJson()), {
         Effect: 'Allow',
         Action: 'test:Action',
         Principal: { Service: 'codedeploy.cn-north-1.amazonaws.com.cn' }
@@ -361,7 +341,7 @@ export = {
         .addAction('test:Action')
         .addServicePrincipal('codedeploy.amazonaws.com', { region: 'cn-north-1' });
 
-      test.deepEqual(stack.resolve(s), {
+      test.deepEqual(stack.resolve(s.toStatementJson()), {
         Effect: 'Allow',
         Action: 'test:Action',
         Principal: { Service: 'codedeploy.cn-north-1.amazonaws.com.cn' }
@@ -376,7 +356,7 @@ export = {
         .addAction('test:Action')
         .addServicePrincipal('test.service-principal.dev');
 
-      test.deepEqual(stack.resolve(s), {
+      test.deepEqual(stack.resolve(s.toStatementJson()), {
         Effect: 'Allow',
         Action: 'test:Action',
         Principal: { Service: 'test.service-principal.dev' }
@@ -392,7 +372,7 @@ export = {
       const stack = new Stack();
       const p = new CompositePrincipal(new ArnPrincipal('i:am:an:arn'));
       const statement = new PolicyStatement().addPrincipal(p);
-      test.deepEqual(stack.resolve(statement), { Effect: 'Allow', Principal: { AWS: 'i:am:an:arn' } });
+      test.deepEqual(stack.resolve(statement.toStatementJson()), { Effect: 'Allow', Principal: { AWS: 'i:am:an:arn' } });
       test.done();
     },
 
@@ -420,10 +400,10 @@ export = {
       const statement = new PolicyStatement().addPrincipal(p);
 
       // add via policy statement
-      statement.addAwsPrincipal('aws-principal-3');
+      statement.addArnPrincipal('aws-principal-3');
       statement.addCondition('cond2', { boom: 123 });
 
-      test.deepEqual(stack.resolve(statement), {
+      test.deepEqual(stack.resolve(statement.toStatementJson()), {
         Condition: {
           cond2: { boom: 123 }
         },
@@ -524,5 +504,30 @@ export = {
       ],
     });
     test.done();
-  }
-};
+  },
+
+  'fromAttributes is equivalent'(test: Test) {
+    const stack = new Stack();
+
+    const doc1 = new PolicyDocument();
+    doc1.addStatements(new PolicyStatement()
+      .addActions('action1', 'action2')
+      .addAllResources()
+      .addArnPrincipal('arn')
+      .addCondition('key', { equals: 'value' }));
+
+    const doc2 = new PolicyDocument();
+    doc2.addStatements(PolicyStatement.fromAttributes({
+      actions: ['action1', 'action2'],
+      resourceArns: ['*'],
+      principals: [new ArnPrincipal('arn')],
+      conditions: {
+        key: { equals: 'value' }
+      }
+    }));
+
+    test.deepEqual(stack.resolve(doc1), stack.resolve(doc2));
+
+    test.done();
+  },
+};

packages/@aws-cdk/aws-kms/test/integ.key.ts

@@ -11,7 +11,7 @@ const key = new Key(stack, 'MyKey', { retain: false });
 key.addToResourcePolicy(new PolicyStatement()
   .addAllResources()
   .addAction('kms:encrypt')
-  .addAwsPrincipal(stack.accountId));
+  .addArnPrincipal(stack.accountId));
 
 key.addAlias('alias/bar');