udondan/iam-floyd/iam-floyd-usage

Using iam-floyd / cdk-iam-floyd

IAM Floyd is a fluent, type-safe AWS IAM policy statement generator. Instead of writing error-prone JSON, you call strongly-typed methods and let the library build the correct policy structure.

It comes in two variants with the same API, released together with the same version number in every language:

• `iam-floyd` (standalone) creates statements as JSON, for the AWS SDKs,

CloudFormation, Terraform or anything else that takes an IAM policy. The packages for Python, Java, .NET and Go are native: no Node.js, no dependencies.

• `cdk-iam-floyd` creates AWS CDK v2 statements: every statement is an

iam.PolicyStatement. The packages for Python, Java, .NET and Go are built with jsii, like the AWS CDK itself, and need Node.js.

The examples in this skill are TypeScript. The API is the same in every language, with names adapted to the language, see Other languages.

Installation

Pin the exact version (e.g. "iam-floyd": "0.850.0" in package.json,

iam-floyd==0.850.0 for pip) — the package is pre-1.0.0 and the API may change.

A new version is released every Monday. CDK v2 requires cdk-iam-floyd >= 0.300.0.

The Go modules are not on GitHub, but on a module proxy under

udondan.github.io/iam-floyd/go, which keeps the newest 30 releases. go get

finds it without any configuration.

Basic import

// TypeScript / ESM
import { Statement } from 'iam-floyd';
import { Statement } from 'cdk-iam-floyd'; // CDK variant
// CommonJS
const { Statement } = require('iam-floyd');

The statement providers (Ec2, S3, ...) live in a sub-package or namespace statement. The core classes (Operator, Collection, the policy documents, AwsManagedPolicy, AwsServicePrincipal) live in the package itself:

In Go, both imports are needed: statement.NewEc2(nil) and iamfloyd.NewManagedPolicyDocument(...).

Core vocabulary — the fluent chain

Every statement follows this readable pattern:

new Statement.<Service>()  // pick the AWS service
  .allow() | .deny()       // effect  (allow is the default)
  .toXxx()                 // actions  ("to do something")
  .onXxx()                 // resources ("on a specific resource")
  .ifXxx()                 // conditions ("if a condition is met")

Effect — allow() / deny()

The default effect is Allow, so .allow() is optional but improves readability.

new Statement.Ec2().allow().toStartInstances();
new Statement.Ec2().deny().toStopInstances();

Actions — to*()

Every documented IAM action has a typed to*() method:

new Statement.Ec2()
  .allow()
  .toStartInstances()
  .toStopInstances()
  .toDescribeInstances();

Bulk action helpers:

allMatchingActions and access-level methods expand to an explicit list at

call time — they won't auto-update if AWS adds new actions later.

Use .compact() after access-level methods to collapse the list into wildcard patterns (reduces policy size, but future AWS actions may match unexpectedly):

new Statement.Ec2().allow().allReadActions().allListActions().compact();
// produces: ["ec2:Describe*", "ec2:Get*", ...]

Missing action? Use the generic to() escape hatch:

.to('missingAction')  // becomes ec2:missingAction

Resources — on*()

Every resource type has an on*() method that builds the correct ARN:

new Statement.S3()
  .allow()
  .allActions()
  .onBucket('example-bucket')
  .onObject('example-bucket', 'some/prefix/*');
new Statement.Lambda().allow().toInvokeFunction().onFunction('my-function'); // optional: account, region, partition params
new Statement.Ec2()
  .allow()
  .toStartInstances()
  .toStopInstances()
  .onInstance('i-1234567890abcdef0');

In cdk-iam-floyd, omitting account/region defaults to the CDK stack's values. In iam-floyd (standalone), they default to *.

In cdk-iam-floyd, the on*() methods also take a CDK construct (L1 or L2) in place of the name, if aws-cdk-lib has a reference interface for it (aws-cdk-lib/interfaces, e.g. IBucketRef). The ARN of the construct is used; account, region and partition are ignored:

const bucket = new s3.Bucket(this, 'Bucket');
new Statement.S3().allow().toListBucket().onBucket(bucket);
new Statement.Lambda().allow().toInvokeFunction().onFunction(myFunction); // lambda.IFunction

Override defaults for multiple resources using in*() / in():

new Statement.Lambda()
  .allow()
  .toUpdateFunctionCode()
  .inAccount('098765432109')
  .inRegion('us-east-1')
  .inPartition('aws')
  .onFunction('my-function-1')
  .onFunction('my-function-2')
  // Shorthand:
  .in('098765432109', 'us-east-1', 'aws')
  .onFunction('my-function-1')
  // Switch context mid-statement:
  .in('111111111111', 'eu-west-1', 'aws')
  .onFunction('cross-account-function');

in*() methods set defaults only for resources added after them — call them

before the on*() calls they should affect.

Already have an ARN? Use the generic on():

.on('arn:aws:s3:::my-bucket', 'arn:aws:s3:::another-bucket')

Conditions — if*()

Every documented condition key has an if*() method. Global AWS conditions start with ifAws*.

new Statement.Ec2()
  .allow()
  .toStartInstances()
  .ifEncrypted() // Bool condition
  .ifInstanceType(['t3.micro', 't3.nano']) // StringLike with multiple values
  .ifAssociatePublicIpAddress(false) // Bool: false
  .ifAwsRequestTag('Owner', 'alice'); // Tag condition

Multiple conditions on one statement are AND-ed together. For OR logic, use multiple statements.

Override the operator (last argument):

.ifAwsRequestTag('Env', '*John*', 'StringEquals')
// Or use the typed Operator class:
import { Operator } from 'iam-floyd';
.ifAwsRequestTag('Env', '*John*', Operator.stringEquals)

Deny + condition operator trap: When using deny() with a tag condition, the

operator direction matters a lot. The default operator on most if*() methods is

StringLike. So .deny().toStopInstances().ifResourceTag('Owner', 'alice') means

"deny stop _when_ the tag matches alice" — which denies the owner, not others.

To deny everyone _except_ the owner, flip it:

.deny().toStopInstances().ifResourceTag('Owner', 'alice', Operator.stringNotEquals)

Complex operators (ForAllValues, ForAnyValue, IfExists):

import { Operator } from 'iam-floyd';
new Statement.Dynamodb()
  .allow()
  .toGetItem()
  .onTable('Thread')
  .ifAttributes(
    ['ID', 'Message'],
    new Operator().stringEquals().forAllValues(),
  );
new Statement.Ec2()
  .allow()
  .toStartInstances()
  .ifAwsRequestTag(
    'Environment',
    ['Prod', 'Dev'],
    new Operator().stringEquals().ifExists(),
  );

Missing condition? Use the generic if():

.if('ec2:missingCondition', 'some-value')  // defaults to StringLike

Principals — for*()

In cdk-iam-floyd, avoid building assume-role policies with iam-floyd — use

CDK's iam.PolicyDocument / iam.ManagedPolicy with a principal instead. iam-floyd's

for*() methods are mainly useful for resource-based policies (S3 bucket policies, etc.)

new Statement.Sts()
  .allow()
  .toAssumeRole()
  .forAccount('123456789012') // Account root principal
  .forUser('123456789012', 'Alice', 'Bob') // IAM users (same account)
  .forRole('123456789012', 'my-role') // IAM role ARN
  .forService('lambda.amazonaws.com') // AWS service
  .forService(AwsServicePrincipal.ECS_TASKS) // AWS service, by constant
  .forFederatedCognito() // Cognito identity pool
  .forPublic() // Principal: *
  .for('arn:foo:bar'); // Arbitrary ARN
// CDK only — accepts iam.IPrincipal objects:
new Statement.Sts()
  .allow()
  .toAssumeRole()
  .forCdkPrincipal(
    new iam.ServicePrincipal('sns.amazonaws.com'),
    new iam.ServicePrincipal('lambda.amazonaws.com'),
  );

NotAction / NotResource / NotPrincipal

Understand these well before using — they can be surprisingly permissive.

// Allow everything EXCEPT delete on this bucket:
new Statement.S3()
  .allow()
  .notAction()
  .toDeleteBucket()
  .onBucket('example-bucket');
// Deny all S3 actions NOT on this bucket:
new Statement.S3()
  .allow()
  .notResource()
  .toDeleteBucket()
  .onBucket('example-bucket');
// Deny all S3 actions for anyone who is NOT Bob:
new Statement.S3()
  .deny()
  .allActions()
  .notPrincipal()
  .forUser('1234567890', 'Bob')
  .onObject('example-bucket', '*');

Statement SID

new Statement.Ec2('AllowEC2ReadOnly').allow().allReadActions();

Building a complete policy