alchemy 0.2.3 → 0.2.4

package/lib/aws/oidc/github-oidc-provider.js

@@ -5,6 +5,74 @@ import { OIDCProvider } from "./oidc-provider";
  * @see https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services#adding-the-identity-provider-to-aws
  */
 const DEFAULT_GITHUB_THUMBPRINT = "6938fd4d98bab03faadb97b34396831e3780aea1";
+/**
+ * GitHub-specific OIDC Provider Resource
+ *
+ * A simplified wrapper around OIDCProvider that automatically sets the correct
+ * thumbprint for GitHub Actions. This is the recommended way to set up OIDC
+ * authentication for GitHub Actions workflows.
+ *
+ * @example
+ * // Create a GitHub OIDC provider for all branches
+ * const provider = await GitHubOIDCProvider("github", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   roleArn: "arn:aws:iam::123456789012:role/github-actions"
+ * });
+ *
+ * @example
+ * // Create a GitHub OIDC provider with branch and environment restrictions
+ * const provider = await GitHubOIDCProvider("github-restricted", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   branches: ["main", "prod"],
+ *   environments: ["staging", "production"],
+ *   roleArn: "arn:aws:iam::123456789012:role/github-actions",
+ *   maxSessionDuration: 7200
+ * });
+ *
+ * @example
+ * // Complete setup with IAM role and OIDC provider
+ * import { Role, getAccountId } from "../aws";
+ *
+ * // Get the AWS account ID
+ * const accountId = await getAccountId();
+ *
+ * // Create the IAM role that GitHub Actions will assume
+ * const githubRole = await Role("github-oidc-role", {
+ *   roleName: "github-actions-role",
+ *   assumeRolePolicy: {
+ *     Version: "2012-10-17",
+ *     Statement: [
+ *       {
+ *         Sid: "GitHubOIDC",
+ *         Effect: "Allow",
+ *         Principal: {
+ *           Federated: `arn:aws:iam::${accountId}:oidc-provider/token.actions.githubusercontent.com`
+ *         },
+ *         Action: "sts:AssumeRoleWithWebIdentity",
+ *         Condition: {
+ *           StringEquals: {
+ *             "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
+ *           },
+ *           StringLike: {
+ *             "token.actions.githubusercontent.com:sub": "repo:my-org/my-repo:*"
+ *           }
+ *         }
+ *       }
+ *     ]
+ *   },
+ *   // Add required managed policies or inline policies for your use case
+ *   managedPolicyArns: ["arn:aws:iam::aws:policy/ReadOnlyAccess"]
+ * });
+ *
+ * // Create the OIDC provider using the role
+ * const provider = await GitHubOIDCProvider("github-oidc", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   roleArn: githubRole.arn
+ * });
+ */
 export const GitHubOIDCProvider = async (id, props) => {
     return OIDCProvider(id, {
         owner: props.owner,

package/lib/aws/oidc/oidc-provider.d.ts

@@ -6,36 +6,45 @@ import { Resource } from "../../resource";
 export interface OIDCProviderProps {
     /**
      * The GitHub organization or user that owns the repository
+     * Example: "my-org" or "my-username"
      */
     owner: string;
     /**
      * The name of the GitHub repository
+     * Example: "my-repo"
      */
     repository: string;
     /**
      * Optional list of branches to restrict access to
      * If not provided, all branches will be allowed
+     * Example: ["main", "prod"]
      */
     branches?: string[];
     /**
      * Optional list of environments to restrict access to
      * If not provided, all environments will be allowed
+     * Example: ["staging", "production"]
      */
     environments?: string[];
     /**
      * The ARN of the IAM role to be assumed
+     * Format: arn:aws:iam::account-id:role/role-name
      */
     roleArn: string;
     /**
-     * Optional maximum session duration in seconds (default: 3600)
+     * Optional maximum session duration in seconds
+     * Default: 3600 (1 hour)
+     * Range: 900-43200 seconds (15 minutes to 12 hours)
      */
     maxSessionDuration?: number;
     /**
      * Thumbprint for the OIDC provider
+     * Used to verify the identity provider's server certificate
      */
     thumbprint: string;
     /**
-     * Optional AWS region (defaults to AWS_REGION environment variable)
+     * Optional AWS region
+     * @default AWS_REGION environment variable
      */
     region?: string;
 }
@@ -45,14 +54,13 @@ export interface OIDCProviderProps {
 export interface OIDCProvider extends Resource<"aws::OIDCProvider">, OIDCProviderProps {
     /**
      * The ARN of the OIDC provider
+     * Format: arn:aws:iam::account-id:oidc-provider/token.actions.githubusercontent.com
      */
     providerArn: string;
     /**
      * Time at which the provider was created
+     * Unix timestamp in milliseconds
      */
     createdAt: number;
 }
-/**
- * Resource for configuring AWS OIDC provider for GitHub Actions
- */
-export declare const OIDCProvider: ((this: Context<OIDCProvider>, id: string, props: OIDCProviderProps) => Promise<OIDCProvider>) | (((this: any, id: string, props?: OIDCProviderProps | undefined) => never) & (new (_: never) => never));
+export declare const OIDCProvider: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<OIDCProvider>, id: string, props: OIDCProviderProps) => Promise<OIDCProvider>);

package/lib/aws/oidc/oidc-provider.js

@@ -2,13 +2,34 @@ import { CreateOpenIDConnectProviderCommand, DeleteOpenIDConnectProviderCommand,
 import { Resource } from "../../resource";
 import { getAccountId } from "../account-id";
 /**
- * Unique identifier for our trust policy statement
- * Used to track and remove our specific statement without affecting others
+ * AWS OIDC Provider Resource for GitHub Actions
+ *
+ * Creates and manages an OpenID Connect (OIDC) identity provider in AWS IAM
+ * for GitHub Actions workflows. This enables secure, token-based authentication
+ * between GitHub Actions and AWS without storing long-term credentials.
+ *
+ * @example
+ * // Create an OIDC provider for all branches
+ * const provider = await OIDCProvider("github", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   roleArn: "arn:aws:iam::123456789012:role/github-actions",
+ *   thumbprint: "6938fd4d98bab03faadb97b34396831e3780aea1"
+ * });
+ *
+ * @example
+ * // Create an OIDC provider restricted to specific branches and environments
+ * const provider = await OIDCProvider("github-restricted", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   branches: ["main", "prod"],
+ *   environments: ["staging", "production"],
+ *   roleArn: "arn:aws:iam::123456789012:role/github-actions",
+ *   thumbprint: "6938fd4d98bab03faadb97b34396831e3780aea1",
+ *   maxSessionDuration: 7200
+ * });
  */
 const TRUST_POLICY_SID = "GitHubOIDCTrust";
-/**
- * Resource for configuring AWS OIDC provider for GitHub Actions
- */
 export const OIDCProvider = Resource("aws::OIDCProvider", async function (id, props) {
     // Initialize AWS SDK client
     const client = new IAMClient({

package/lib/aws/policy-attachment.d.ts

@@ -1,9 +1,52 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
+/**
+ * Properties for creating or updating a policy attachment
+ */
 export interface PolicyAttachmentProps {
+    /**
+     * ARN of the IAM policy to attach
+     */
     policyArn: string;
+    /**
+     * Name of the IAM role to attach the policy to
+     */
     roleName: string;
 }
+/**
+ * Output returned after policy attachment creation/update
+ */
 export interface PolicyAttachment extends Resource<"iam::PolicyAttachment">, PolicyAttachmentProps {
 }
-export declare const PolicyAttachment: ((this: Context<PolicyAttachment>, id: string, props: PolicyAttachmentProps) => Promise<PolicyAttachment>) | (((this: any, id: string, props?: PolicyAttachmentProps | undefined) => never) & (new (_: never) => never));
+/**
+ * AWS IAM Policy Attachment Resource
+ *
+ * Attaches an IAM policy to a role, enabling the role to use the permissions defined in the policy.
+ *
+ * @example
+ * // Attach an AWS managed policy to a role
+ * const adminAccess = await PolicyAttachment("admin-policy", {
+ *   policyArn: "arn:aws:iam::aws:policy/AdministratorAccess",
+ *   roleName: role.name
+ * });
+ *
+ * @example
+ * // Attach a custom policy to a role
+ * const customPolicy = await PolicyAttachment("custom-policy", {
+ *   policyArn: policy.arn,
+ *   roleName: role.name
+ * });
+ *
+ * @example
+ * // Attach multiple policies to a role
+ * const s3Access = await PolicyAttachment("s3-access", {
+ *   policyArn: "arn:aws:iam::aws:policy/AmazonS3FullAccess",
+ *   roleName: role.name
+ * });
+ *
+ * const sqsAccess = await PolicyAttachment("sqs-access", {
+ *   policyArn: "arn:aws:iam::aws:policy/AmazonSQSFullAccess",
+ *   roleName: role.name
+ * });
+ */
+export declare const PolicyAttachment: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<PolicyAttachment>, id: string, props: PolicyAttachmentProps) => Promise<PolicyAttachment>);

package/lib/aws/policy-attachment.js

@@ -1,6 +1,37 @@
 import { AttachRolePolicyCommand, DetachRolePolicyCommand, IAMClient, NoSuchEntityException, } from "@aws-sdk/client-iam";
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
+/**
+ * AWS IAM Policy Attachment Resource
+ *
+ * Attaches an IAM policy to a role, enabling the role to use the permissions defined in the policy.
+ *
+ * @example
+ * // Attach an AWS managed policy to a role
+ * const adminAccess = await PolicyAttachment("admin-policy", {
+ *   policyArn: "arn:aws:iam::aws:policy/AdministratorAccess",
+ *   roleName: role.name
+ * });
+ *
+ * @example
+ * // Attach a custom policy to a role
+ * const customPolicy = await PolicyAttachment("custom-policy", {
+ *   policyArn: policy.arn,
+ *   roleName: role.name
+ * });
+ *
+ * @example
+ * // Attach multiple policies to a role
+ * const s3Access = await PolicyAttachment("s3-access", {
+ *   policyArn: "arn:aws:iam::aws:policy/AmazonS3FullAccess",
+ *   roleName: role.name
+ * });
+ *
+ * const sqsAccess = await PolicyAttachment("sqs-access", {
+ *   policyArn: "arn:aws:iam::aws:policy/AmazonSQSFullAccess",
+ *   roleName: role.name
+ * });
+ */
 export const PolicyAttachment = Resource("iam::PolicyAttachment", async function (id, props) {
     const client = new IAMClient({});
     if (this.phase === "delete") {

package/lib/aws/policy.d.ts

@@ -1,34 +1,193 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
+/**
+ * Type of effect for a policy statement
+ */
 export type Effect = "Allow" | "Deny";
+/**
+ * A single statement within an IAM policy document
+ */
 export interface PolicyStatement {
+    /**
+     * Optional identifier for the statement
+     */
     Sid?: string;
+    /**
+     * Whether to allow or deny the specified actions
+     */
     Effect: Effect;
+    /**
+     * Actions that the policy allows or denies
+     */
     Action: string | string[];
+    /**
+     * Resources that the policy applies to
+     */
     Resource?: string | string[];
+    /**
+     * Additional conditions for when the policy applies
+     */
     Condition?: Record<string, Record<string, string | string[]>>;
+    /**
+     * AWS principals that the policy applies to
+     */
     Principal?: Record<string, string | string[]>;
+    /**
+     * AWS principals that the policy explicitly does not apply to
+     */
     NotPrincipal?: Record<string, string | string[]>;
+    /**
+     * Actions that are explicitly not included in this statement
+     */
     NotAction?: string | string[];
+    /**
+     * Resources that are explicitly not included in this statement
+     */
     NotResource?: string | string[];
 }
+/**
+ * An IAM policy document containing one or more statements
+ */
 export interface PolicyDocument {
+    /**
+     * Policy language version (must be "2012-10-17")
+     */
     Version: "2012-10-17";
+    /**
+     * List of policy statements
+     */
     Statement: PolicyStatement[];
 }
+/**
+ * Properties for creating or updating an IAM policy
+ */
 export interface PolicyProps {
+    /**
+     * Name of the policy
+     */
     policyName: string;
+    /**
+     * Policy document defining the permissions
+     */
     document: PolicyDocument;
+    /**
+     * Optional description of the policy's purpose
+     */
     description?: string;
+    /**
+     * Optional path prefix for the policy
+     */
     path?: string;
+    /**
+     * Optional resource tags
+     */
     tags?: Record<string, string>;
 }
+/**
+ * Output returned after IAM policy creation/update
+ */
 export interface Policy extends Resource<"iam::Policy">, PolicyProps {
+    /**
+     * ARN of the policy
+     */
     arn: string;
+    /**
+     * ID of the default policy version
+     */
     defaultVersionId: string;
+    /**
+     * Number of entities the policy is attached to
+     */
     attachmentCount: number;
+    /**
+     * When the policy was created
+     */
     createDate: Date;
+    /**
+     * When the policy was last updated
+     */
     updateDate: Date;
+    /**
+     * Whether the policy can be attached to IAM users/roles
+     */
     isAttachable: boolean;
 }
-export declare const Policy: ((this: Context<Policy>, id: string, props: PolicyProps) => Promise<Policy>) | (((this: any, id: string, props?: PolicyProps | undefined) => never) & (new (_: never) => never));
+/**
+ * AWS IAM Policy Resource
+ *
+ * Creates and manages IAM policies that define permissions for AWS services and resources.
+ * Supports automatic versioning and updates when policy content changes.
+ *
+ * @example
+ * // Create a basic S3 bucket access policy
+ * const s3Policy = await Policy("bucket-access", {
+ *   policyName: "s3-bucket-access",
+ *   document: {
+ *     Version: "2012-10-17",
+ *     Statement: [{
+ *       Effect: "Allow",
+ *       Action: [
+ *         "s3:GetObject",
+ *         "s3:PutObject"
+ *       ],
+ *       Resource: `${bucket.arn}/*`
+ *     }]
+ *   }
+ * });
+ *
+ * @example
+ * // Create a policy with multiple statements and conditions
+ * const apiPolicy = await Policy("api-access", {
+ *   policyName: "api-gateway-access",
+ *   document: {
+ *     Version: "2012-10-17",
+ *     Statement: [
+ *       {
+ *         Sid: "InvokeAPI",
+ *         Effect: "Allow",
+ *         Action: "execute-api:Invoke",
+ *         Resource: `${api.executionArn}/*`,
+ *         Condition: {
+ *           StringEquals: {
+ *             "aws:SourceVpc": vpc.id
+ *           }
+ *         }
+ *       },
+ *       {
+ *         Sid: "ReadLogs",
+ *         Effect: "Allow",
+ *         Action: [
+ *           "logs:GetLogEvents",
+ *           "logs:FilterLogEvents"
+ *         ],
+ *         Resource: `${api.logGroupArn}:*`
+ *       }
+ *     ]
+ *   },
+ *   description: "Allows invoking API Gateway endpoints and reading logs",
+ *   tags: {
+ *     Service: "API Gateway",
+ *     Environment: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a policy that denies access based on tags
+ * const denyPolicy = await Policy("deny-production", {
+ *   policyName: "deny-production-access",
+ *   document: {
+ *     Version: "2012-10-17",
+ *     Statement: [{
+ *       Effect: "Deny",
+ *       Action: "*",
+ *       Resource: "*",
+ *       Condition: {
+ *         StringEquals: {
+ *           "aws:ResourceTag/Environment": "production"
+ *         }
+ *       }
+ *     }]
+ *   }
+ * });
+ */
+export declare const Policy: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Policy>, id: string, props: PolicyProps) => Promise<Policy>);

package/lib/aws/policy.js

@@ -1,5 +1,83 @@
 import { CreatePolicyCommand, CreatePolicyVersionCommand, DeletePolicyCommand, DeletePolicyVersionCommand, GetPolicyCommand, GetPolicyVersionCommand, IAMClient, ListPolicyVersionsCommand, NoSuchEntityException, } from "@aws-sdk/client-iam";
 import { Resource } from "../resource";
+/**
+ * AWS IAM Policy Resource
+ *
+ * Creates and manages IAM policies that define permissions for AWS services and resources.
+ * Supports automatic versioning and updates when policy content changes.
+ *
+ * @example
+ * // Create a basic S3 bucket access policy
+ * const s3Policy = await Policy("bucket-access", {
+ *   policyName: "s3-bucket-access",
+ *   document: {
+ *     Version: "2012-10-17",
+ *     Statement: [{
+ *       Effect: "Allow",
+ *       Action: [
+ *         "s3:GetObject",
+ *         "s3:PutObject"
+ *       ],
+ *       Resource: `${bucket.arn}/*`
+ *     }]
+ *   }
+ * });
+ *
+ * @example
+ * // Create a policy with multiple statements and conditions
+ * const apiPolicy = await Policy("api-access", {
+ *   policyName: "api-gateway-access",
+ *   document: {
+ *     Version: "2012-10-17",
+ *     Statement: [
+ *       {
+ *         Sid: "InvokeAPI",
+ *         Effect: "Allow",
+ *         Action: "execute-api:Invoke",
+ *         Resource: `${api.executionArn}/*`,
+ *         Condition: {
+ *           StringEquals: {
+ *             "aws:SourceVpc": vpc.id
+ *           }
+ *         }
+ *       },
+ *       {
+ *         Sid: "ReadLogs",
+ *         Effect: "Allow",
+ *         Action: [
+ *           "logs:GetLogEvents",
+ *           "logs:FilterLogEvents"
+ *         ],
+ *         Resource: `${api.logGroupArn}:*`
+ *       }
+ *     ]
+ *   },
+ *   description: "Allows invoking API Gateway endpoints and reading logs",
+ *   tags: {
+ *     Service: "API Gateway",
+ *     Environment: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a policy that denies access based on tags
+ * const denyPolicy = await Policy("deny-production", {
+ *   policyName: "deny-production-access",
+ *   document: {
+ *     Version: "2012-10-17",
+ *     Statement: [{
+ *       Effect: "Deny",
+ *       Action: "*",
+ *       Resource: "*",
+ *       Condition: {
+ *         StringEquals: {
+ *           "aws:ResourceTag/Environment": "production"
+ *         }
+ *       }
+ *     }]
+ *   }
+ * });
+ */
 export const Policy = Resource("iam::Policy", async function (id, props) {
     const client = new IAMClient({});
     const policyArn = `arn:aws:iam::${process.env.AWS_ACCOUNT_ID}:policy${props.path || "/"}${props.policyName}`;

package/lib/aws/queue.d.ts

@@ -1,5 +1,8 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
+/**
+ * Properties for creating or updating an SQS queue
+ */
 export interface QueueProps {
     /**
      * Name of the queue
@@ -11,22 +14,101 @@ export interface QueueProps {
      * If true, the queueName must end with .fifo suffix
      */
     fifo?: boolean;
+    /**
+     * The length of time (in seconds) that a message received from a queue will be invisible to other receiving components
+     * Default: 30 seconds
+     */
     visibilityTimeout?: number;
+    /**
+     * The length of time (in seconds) for which Amazon SQS retains a message
+     * Default: 345600 seconds (4 days)
+     */
     messageRetentionPeriod?: number;
+    /**
+     * The limit of how many bytes a message can contain before Amazon SQS rejects it
+     * Default: 262144 bytes (256 KB)
+     */
     maximumMessageSize?: number;
+    /**
+     * The time in seconds that the delivery of all messages in the queue will be delayed
+     * Default: 0 seconds
+     */
     delaySeconds?: number;
+    /**
+     * The length of time (in seconds) for which a ReceiveMessage action waits for a message to arrive
+     * Default: 0 seconds
+     */
     receiveMessageWaitTimeSeconds?: number;
     /**
      * Enables content-based deduplication for FIFO queues.
      * Only applicable when fifo is true.
      */
     contentBasedDeduplication?: boolean;
+    /**
+     * Specifies whether message deduplication occurs at the message group or queue level
+     * Only applicable when fifo is true
+     */
     deduplicationScope?: "messageGroup" | "queue";
+    /**
+     * Specifies whether the FIFO queue throughput quota applies to the entire queue or per message group
+     * Only applicable when fifo is true
+     */
     fifoThroughputLimit?: "perQueue" | "perMessageGroupId";
+    /**
+     * Resource tags for the queue
+     */
     tags?: Record<string, string>;
 }
+/**
+ * Output returned after SQS queue creation/update
+ */
 export interface Queue extends Resource<"sqs::Queue">, QueueProps {
+    /**
+     * ARN of the queue
+     */
     arn: string;
+    /**
+     * URL of the queue
+     */
     url: string;
 }
-export declare const Queue: ((this: Context<Queue>, id: string, props: QueueProps) => Promise<Queue>) | (((this: any, id: string, props?: QueueProps | undefined) => never) & (new (_: never) => never));
+/**
+ * AWS SQS Queue Resource
+ *
+ * Creates and manages Amazon SQS queues with support for both standard and FIFO queues.
+ * Handles queue creation, attribute configuration, and automatic cleanup of deleted queues.
+ *
+ * @example
+ * // Create a standard queue with custom visibility timeout
+ * const standardQueue = await Queue("my-queue", {
+ *   queueName: "my-queue",
+ *   visibilityTimeout: 30,
+ *   tags: {
+ *     Environment: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a FIFO queue with content-based deduplication
+ * const fifoQueue = await Queue("orders-queue", {
+ *   queueName: "orders-queue.fifo",
+ *   fifo: true,
+ *   contentBasedDeduplication: true,
+ *   visibilityTimeout: 30,
+ *   tags: {
+ *     Environment: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a queue with custom message retention and size
+ * const customQueue = await Queue("large-messages", {
+ *   queueName: "large-messages",
+ *   messageRetentionPeriod: 345600,  // 4 days
+ *   maximumMessageSize: 262144,      // 256 KB
+ *   visibilityTimeout: 60,
+ *   delaySeconds: 5,
+ *   receiveMessageWaitTimeSeconds: 20
+ * });
+ */
+export declare const Queue: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Queue>, id: string, props: QueueProps) => Promise<Queue>);