Add the aws.iam#supportedPrincipalTypes trait

This commit introduces a trait that indicates which IAM principal
types can use a service or operation. This is useful for users of a
service when writing IAM policies.

docs/source/1.0/spec/aws/aws-iam.rst

@@ -487,6 +487,53 @@ operation for it to complete successfully.
             }
         }
 
+
+.. smithy-trait:: aws.iam#supportedPrincipalTypes
+.. _aws.iam#supportedPrincipalTypes-trait:
+
+-----------------------------------------
+``aws.iam#supportedPrincipalTypes`` trait
+-----------------------------------------
+
+Summary
+    The `IAM principal types`_ that can use the service or operation.
+Trait selector
+    ``:test(service, operation)``
+Value type
+    ``list<string>`` where each string is an IAM principal type: ``Root``,
+    ``IAMUser``, ``IAMRole``, or ``FederatedUser``.
+
+Operations that are not annotated with the ``supportedPrincipalTypes`` trait
+inherit the ``supportedPrincipalTypes`` of the service they are bound to.
+
+The following example defines two operations:
+
+* OperationA defines an explicit list of the IAM principal types it supports
+  using the ``supportedPrincipalTypes`` trait.
+* OperationB is not annotated with the ``supportedPrincipalTypes`` trait, so
+  the IAM principal types supported by this operation are the principal types
+  applied to the service.
+
+.. tabs::
+
+    .. code-tab:: smithy
+
+        namespace smithy.example
+
+        use aws.iam#supportedPrincipalTypes
+
+        @supportedPrincipalTypes(["Root", "IAMUser", "IAMRole", "FederatedUser"])
+        service MyService {
+            version: "2020-07-02",
+            operations: [OperationA, OperationB],
+        }
+
+        @supportedPrincipalTypes(["Root"])
+        operation OperationA {}
+
+        operation OperationB {}
+
+
 .. _deriving-condition-keys:
 
 -----------------------
@@ -613,3 +660,4 @@ The computed condition keys for the service are:
 .. _condition operators: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html
 .. _Amazon Resource Name (ARN): https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html
 .. _ISO 8601: http://www.w3.org/TR/NOTE-datetime
+.. _IAM principal types: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html

smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/SupportedPrincipalTypesTrait.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.smithy.aws.iam.traits;
+
+import java.util.List;
+import software.amazon.smithy.model.FromSourceLocation;
+import software.amazon.smithy.model.SourceLocation;
+import software.amazon.smithy.model.shapes.ShapeId;
+import software.amazon.smithy.model.traits.StringListTrait;
+import software.amazon.smithy.utils.ToSmithyBuilder;
+
+public final class SupportedPrincipalTypesTrait extends StringListTrait
+        implements ToSmithyBuilder<SupportedPrincipalTypesTrait> {
+    public static final ShapeId ID = ShapeId.from("aws.iam#supportedPrincipalTypes");
+
+    public SupportedPrincipalTypesTrait(List<String> principals, FromSourceLocation sourceLocation) {
+        super(ID, principals, sourceLocation);
+    }
+
+    public SupportedPrincipalTypesTrait(List<String> principals) {
+        this(principals, SourceLocation.NONE);
+    }
+
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    public static final class Provider extends StringListTrait.Provider<SupportedPrincipalTypesTrait> {
+        public Provider() {
+            super(ID, SupportedPrincipalTypesTrait::new);
+        }
+    }
+
+    @Override
+    public Builder toBuilder() {
+        return builder().sourceLocation(getSourceLocation()).values(getValues());
+    }
+
+    public static final class Builder extends StringListTrait.Builder<SupportedPrincipalTypesTrait, Builder> {
+        private Builder() {}
+
+        @Override
+        public SupportedPrincipalTypesTrait build() {
+            return new SupportedPrincipalTypesTrait(getValues(), getSourceLocation());
+        }
+    }
+}

smithy-aws-iam-traits/src/main/resources/META-INF/services/software.amazon.smithy.model.traits.TraitService

@@ -3,3 +3,4 @@ software.amazon.smithy.aws.iam.traits.ConditionKeysTrait$Provider
 software.amazon.smithy.aws.iam.traits.DefineConditionKeysTrait$Provider
 software.amazon.smithy.aws.iam.traits.DisableConditionKeyInferenceTrait$Provider
 software.amazon.smithy.aws.iam.traits.RequiredActionsTrait$Provider
+software.amazon.smithy.aws.iam.traits.SupportedPrincipalTypesTrait$Provider

smithy-aws-iam-traits/src/main/resources/META-INF/smithy/aws.iam.json

@@ -58,6 +58,18 @@
                 "smithy.api#documentation": "Other actions that the invoker must be authorized to perform when executing the targeted operation."
             }
         },
+        "aws.iam#supportedPrincipalTypes": {
+            "type": "list",
+            "member": {
+                "target": "aws.iam#PrincipalType"
+            },
+            "traits": {
+                "smithy.api#trait": {
+                    "selector": ":test(service, operation)"
+                },
+                "smithy.api#documentation": "The principal types that can use the service or operation."
+            }
+        },
         "aws.iam#IamIdentifier": {
             "type": "string",
             "traits": {
@@ -114,6 +126,19 @@
                     {"value": "ArrayOfIPAddress", "name": "ARRAY_OF_IP_ADDRESS"}
                 ]
             }
+        },
+        "aws.iam#PrincipalType": {
+            "type": "string",
+            "traits": {
+                "smithy.api#private": {},
+                "smithy.api#documentation": "An IAM policy principal type.",
+                "smithy.api#enum": [
+                    {"value": "Root", "name": "ROOT"},
+                    {"value": "IAMUser", "name": "IAM_USER"},
+                    {"value": "IAMRole", "name": "IAM_ROLE"},
+                    {"value": "FederatedUser", "name": "FEDERATED_USER"}
+                ]
+            }
         }
     }
 }

smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/SupportedPrincipalTypesTraitTest.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.smithy.aws.iam.traits;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.containsInAnyOrder;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.junit.jupiter.api.Test;
+import software.amazon.smithy.model.Model;
+import software.amazon.smithy.model.shapes.Shape;
+import software.amazon.smithy.model.shapes.ShapeId;
+
+public class SupportedPrincipalTypesTraitTest {
+    @Test
+    public void loadsFromModel() {
+        Model result = Model.assembler()
+                .discoverModels(getClass().getClassLoader())
+                .addImport(getClass().getResource("supported-principal-types.smithy"))
+                .assemble()
+                .unwrap();
+
+        Shape myService = result.expectShape(ShapeId.from("smithy.example#MyService"));
+        Shape myOperation = result.expectShape(ShapeId.from("smithy.example#MyOperation"));
+
+        assertTrue(myService.hasTrait(SupportedPrincipalTypesTrait.class));
+        assertThat(myService.expectTrait(SupportedPrincipalTypesTrait.class).getValues(), containsInAnyOrder(
+                "IAMUser", "IAMRole"));
+
+        assertTrue(myOperation.hasTrait(SupportedPrincipalTypesTrait.class));
+        assertThat(myOperation.expectTrait(SupportedPrincipalTypesTrait.class).getValues(), containsInAnyOrder(
+                "Root", "FederatedUser"));
+    }
+}

smithy-aws-iam-traits/src/test/resources/software/amazon/smithy/aws/iam/traits/supported-principal-types.smithy

@@ -0,0 +1,9 @@
+$version: "1.0"
+
+namespace smithy.example
+
+@aws.iam#supportedPrincipalTypes(["IAMUser", "IAMRole"])
+operation MyService {}
+
+@aws.iam#supportedPrincipalTypes(["Root", "FederatedUser"])
+operation MyOperation {}