feat: grants are now available through a separate class

[rix0rrr]

Instead of grants being attached to the L2 class, they are now available as separate classes.

For example, for Topic the grants are now available as the TopicGrants class. This class is exposed as a public member: public readonly grants: TopicGrants, and can be used like this:

myTopic.grants.publish(myRole);

The grantPublish etc methods on the L2 are now no longer recommended (though they will not be deprecated immediately to not disrupt existing code too much). Instead, all examples now use the new methods, and a linter will prevent new grantXxx() methods from being added to the L2 level. Instead, Grant classes should be written.

The grants class can also be used if you have an L1, and can be generated for services that don't have L2s yet.

They are currently driven from a datafile, grants.json, in the service module directory. This data source may move to the awscdk-service-spec repo in the future.

Example

An example of a generated grants class, for SNS topics:

/* eslint-disable @stylistic/max-len, eol-last */
import * as sns from "./sns.generated";
import * as iam from "aws-cdk-lib/aws-iam";

/**
 * Properties for TopicGrants
 */
interface TopicGrantsProps {
  /**
   * The resource on which actions will be allowed
   */
  readonly resource: sns.ITopicRef;

  /**
   * The resource with policy on which actions will be allowed
   *
   * @default - No resource policy is created
   */
  readonly policyResource?: iam.IResourceWithPolicyV2;

  /**
   * The encrypted resource on which actions will be allowed
   *
   * @default - No permission is added to the KMS key, even if it exists
   */
  readonly encryptedResource?: iam.IEncryptedResource;
}

/**
 * Collection of grant methods for a ITopicRef
 */
export class TopicGrants {
  /**
   * Creates grants for TopicGrants
   *
   * @internal
   */
  public static _fromTopic(resource: sns.ITopicRef): TopicGrants {
    return new TopicGrants({
      resource: resource,
      encryptedResource: (iam.GrantableResources.isEncryptedResource(resource) ? resource : undefined),
      policyResource: (iam.GrantableResources.isResourceWithPolicy(resource) ? resource : undefined)
    });
  }

  protected readonly resource: sns.ITopicRef;

  protected readonly encryptedResource?: iam.IEncryptedResource;

  protected readonly policyResource?: iam.IResourceWithPolicyV2;

  private constructor(props: TopicGrantsProps) {
    this.resource = props.resource;
    this.encryptedResource = props.encryptedResource;
    this.policyResource = props.policyResource;
  }

  /**
   * Grant topic publishing permissions to the given identity
   */
  public publish(grantee: iam.IGrantable): iam.Grant {
    const actions = ["sns:Publish"];
    const result = (this.policyResource ? iam.Grant.addToPrincipalOrResource({
      actions: actions,
      grantee: grantee,
      resourceArns: [sns.CfnTopic.arnForTopic(this.resource)],
      resource: this.policyResource
    }) : iam.Grant.addToPrincipal({
      actions: actions,
      grantee: grantee,
      resourceArns: [sns.CfnTopic.arnForTopic(this.resource)]
    }));
    this.encryptedResource?.grantOnKey(grantee, "kms:Decrypt", "kms:GenerateDataKey*");
    return result;
  }

  /**
   * Grant topic subscribing permissions to the given identity
   */
  public subscribe(grantee: iam.IGrantable): iam.Grant {
    const actions = ["sns:Subscribe"];
    const result = (this.policyResource ? iam.Grant.addToPrincipalOrResource({
      actions: actions,
      grantee: grantee,
      resourceArns: [sns.CfnTopic.arnForTopic(this.resource)],
      resource: this.policyResource
    }) : iam.Grant.addToPrincipal({
      actions: actions,
      grantee: grantee,
      resourceArns: [sns.CfnTopic.arnForTopic(this.resource)]
    }));
    return result;
  }
}

A few things to note:

• The class can only be created via the static method _from<Resource>(). For now, while we experiment with this idea, this method is marked as internal, hence the _ leading the name.
• If the JSON config for the class contains a keyActions, the generated class will also have an encryptedResource property, that allows the Grants class to add permissions to the key, if it's present. This is done via the IEncryptedResource interface.
• If the JSON config for the class has hasPolicy: true, the generated class will also have a policyResource property, that allows the Grants class to create a resource policy.

Also in this PR

• Cleanup around file pattern handling in spec2cdk, and a slight attempt at making it more obvious that spec2cdk has 2 distinct entry points; no attempt at reconciling these 2 entry points yet, I fear that's going to be a time suck.
• JSON files for a subset of services.

---

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)

[otaviomacedo]

Is this what's going in the resourceArns in the call to Grant.addToPrincipalOrResource?

[rix0rrr]

That's what I was thinking yes

WIP

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

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.