alchemy 0.2.2 → 0.2.4

package/lib/aws/function.js

@@ -3,14 +3,60 @@ import fs from "node:fs";
 import path from "node:path";
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
-async function resolveRegion(client) {
-    const region = client.config.region;
-    if (typeof region === "string")
-        return region;
-    if (typeof region === "function")
-        return region();
-    throw new Error("Could not resolve AWS region");
-}
+/**
+ * AWS Lambda Function Resource
+ *
+ * Creates and manages AWS Lambda functions with support for Node.js runtimes, custom handlers,
+ * environment variables, and function URLs. Handles deployment packaging, IAM role
+ * stabilization, and function updates.
+ *
+ * @example
+ * // Create a basic Lambda function with minimal configuration
+ * const basicFunction = await Function("api-handler", {
+ *   functionName: "api-handler",
+ *   zipPath: "./dist/api.zip",
+ *   roleArn: role.arn,
+ *   runtime: Runtime.nodejs20x,
+ *   handler: "index.handler",
+ *   tags: {
+ *     Environment: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a function with environment variables and custom memory/timeout
+ * const configuredFunction = await Function("worker", {
+ *   functionName: "worker",
+ *   zipPath: "./dist/worker.zip",
+ *   roleArn: role.arn,
+ *   runtime: Runtime.nodejs20x,
+ *   handler: "worker.process",
+ *   memorySize: 512,
+ *   timeout: 30,
+ *   environment: {
+ *     QUEUE_URL: queue.url,
+ *     LOG_LEVEL: "info"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a function with a public URL endpoint and CORS
+ * const apiFunction = await Function("public-api", {
+ *   functionName: "public-api",
+ *   zipPath: "./dist/api.zip",
+ *   roleArn: role.arn,
+ *   handler: "api.handler",
+ *   url: {
+ *     authType: "NONE",
+ *     cors: {
+ *       allowOrigins: ["*"],
+ *       allowMethods: ["GET", "POST"],
+ *       allowHeaders: ["content-type"],
+ *       maxAge: 86400
+ *     }
+ *   }
+ * });
+ */
 export const Function = Resource("lambda::Function", async function (id, props) {
     const client = new LambdaClient({});
     const region = await resolveRegion(client);
@@ -172,3 +218,11 @@ async function zipCode(filePath) {
         platform: "UNIX",
     });
 }
+async function resolveRegion(client) {
+    const region = client.config.region;
+    if (typeof region === "string")
+        return region;
+    if (typeof region === "function")
+        return region();
+    throw new Error("Could not resolve AWS region");
+}

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

@@ -1,7 +1,88 @@
 import { OIDCProvider, type OIDCProviderProps } from "./oidc-provider";
+/**
+ * Properties for configuring GitHub-specific OIDC provider
+ * Simplified version of OIDCProviderProps that omits the thumbprint
+ * since it's automatically set to GitHub's known value
+ */
 export interface GitHubOIDCProviderProps extends Omit<OIDCProviderProps, "thumbprint"> {
+    /**
+     * 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;
 }
 export type GitHubOIDCProvider = ReturnType<typeof GitHubOIDCProvider>;
+/**
+ * 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 declare const GitHubOIDCProvider: (id: string, props: GitHubOIDCProviderProps) => Promise<OIDCProvider>;

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) => 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) => 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) => 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>);