iam-floyd

IAM Floyd is a fluent interface generator for AWS IAM policy statements. It provides type-safe, auto-completable access to a vast range of AWS IAM entities, including support for:

• 451 Services
• 21,395 Actions
• 2,261 Resource Types
• 2,378 Condition keys

Note on Stability: This project is currently in an experimental phase (pre-1.0.0). The API is subject to change as new features are implemented. It is highly recommended to use an exact version in your package.json to avoid breaking changes.

IAM Floyd provides two distinct package variants depending on your integration needs:

1. iam-floyd: Use this package if you need to generate IAM policy statements for use with the AWS SDK, Boto3, or any other environment where you manually construct policy JSON.

2. cdk-iam-floyd: Use this package if you are working within the AWS CDK framework. It extends the standard iam.PolicyStatement to provide integrated IAM Floyd capabilities directly within your CDK constructs.

Using IAM Floyd provides several advantages over writing raw JSON IAM policies:

• Type Safety and IntelliSense: All actions, conditions, and resource types are discoverable via code suggestion. This prevents typos that would otherwise be silently accepted by AWS IAM.
• Access Level Helpers: Instead of manual wildcards, you can use semantic methods like .allWriteActions() or .allReadActions() to manage permissions.
• Regex Support: You can select actions using regular expressions, providing more precision than standard IAM wildcards.
• Simplified Resource Management: The package provides specialized methods for resource types (like S3 buckets and objects) that handle complex ARN patterns automatically, reducing the risk of common mistakes (e.g., forgetting to include both the bucket and the object path).

Both packages provide a statement provider for every AWS service (e.g., Ec2). A statement provider is a class containing methods for every available action, resource type, and condition.

Calling a method adds that specific element to the statement. Because every method returns the statement provider instance, you can chain calls together to build a complete policy statement.

IAM Floyd is automatically generated from official AWS Documentation.

• Coverage: Everything documented in the AWS IAM User Guide is covered. If an action or resource is missing, it is likely because it is not yet documented by AWS.
• Updates: The package checks for AWS documentation updates once per day at 2am UTC. If changes are detected, a new package is released immediately.
• Missing items: If you find a missing action/condition, you should report it via the AWS IAM documentation feedback mechanism. Once AWS updates their docs, IAM Floyd will follow shortly after.

You can bundle related permissions into custom classes by subclassing a Statement provider. This allows you to express business intent (e.g., toPushImage()) rather than raw AWS actions, making your code more reusable and readable.

import { Statement } from 'cdk-iam-floyd';

class MyEcr extends Statement.Ecr {
  toPushImage(): this {
    return this.toGetAuthorizationToken()
      .toBatchCheckLayerAvailability()
      .toInitiateLayerUpload()
      .toUploadLayerPart()
      .toCompleteLayerUpload()
      .toPutImage();
  }
}

// Usage
new MyEcr().allow().toPushImage().onRepository('my-repo');

Users should be aware of the following regarding versioning:

• CDK Compatibility: cdk-iam-floyd is based on CDK ^2.0.0. It does not release new packages specifically for every CDK release, as it is designed to be compatible with CDK v2.
• SemVer Status: The package has not yet reached a stable state (v1.0.0). Consequently, breaking changes (such as renamed or deleted IAM actions) may not trigger a major version bump.
• Breaking Changes: If an AWS action is renamed or deleted, your code will break upon updating to the latest release because the corresponding method will no longer exist.
• Automatic Updates: Updates triggered by changes in AWS IAM documentation will result in a minor version update.

The PolicyStatement class is the primary differentiator between the two main packages in this repository: iam-floyd and cdk-iam-floyd.

• iam-floyd: Uses the standard implementation of PolicyStatement.
• cdk-iam-floyd: Uses a specialized version of PolicyStatement designed for AWS CDK compatibility.

Note that the functionality of the PolicyStatement class is composed of multiple classes that are extended in the order of their file names.

IAM Floyd uses a fluent, type-safe API to build IAM policy statements. Every statement follows a predictable pattern of chaining methods together:

1. Pick a service: new Statement.<Service>() (e.g., Ec2, S3, Lambda).
2. Set the effect: .allow() or .deny() (Note: allow() is the default).
3. Specify actions: .toXxx() methods for specific actions.
4. Specify resources: .onXxx() methods for specific resources.
5. Specify conditions: .ifXxx() methods for conditions.

new Statement.Ec2()
  .allow()
  .toStartInstances()
  .onInstance('i-1234567890abcdef0')
  .ifEncrypted();

To use condition operators in your IAM policies, you must import the Operator and Statement classes. The package you import depends on whether you are using AWS CDK:

• Without AWS CDK: Use the iam-floyd package.
• With AWS CDK: Use the cdk-iam-floyd package.

// for use without AWS CDK use the iam-floyd package
import { Operator, Statement } from 'iam-floyd';

// for use with AWS CDK use the cdk-iam-floyd package
import { Operator, Statement } from 'cdk-iam-floyd';

The AwsManagedPolicy class provides a type-safe collection of AWS managed policy names. This allows you to reference standard AWS policies without manually typing strings, reducing errors.

Accessing Policy Names vs ARNs

• Names: The class methods return the policy name (e.g., ReadOnlyAccess).
• ARNs: To use a policy as an ARN, you must prefix the returned name with arn:aws:iam::aws:policy/.

Package Selection

• Use iam-floyd if you are working with the AWS SDK (e.g., AWS SDK v3) without CDK.
• Use cdk-iam-floyd if you are working within an AWS CDK project. The cdk-iam-floyd package includes additional methods to directly create aws_iam.IManagedPolicy objects.

import { AwsManagedPolicy } from 'iam-floyd';
// or
import { AwsManagedPolicy } from 'cdk-iam-floyd';