create-aws-project 1.4.3 → 1.5.0

package/README.md

@@ -4,6 +4,8 @@ Create a new AWS project from scratch including CloudFront, API Gateway, Lambdas
 
 [![npm version](https://img.shields.io/npm/v/create-aws-project.svg)](https://www.npmjs.com/package/create-aws-project)
 
+![AWS Architecture Diagram](./aws-architecture-diagram.svg)
+
 ## Quick Start
 
 ```bash

package/dist/aws/iam.d.ts

@@ -19,12 +19,17 @@ export declare function createIAMClient(region?: string): IAMClient;
  */
 export declare function createCrossAccountIAMClient(region: string, targetAccountId: string): IAMClient;
 /**
- * Creates an IAM deployment user with path /deployment/
+ * Creates an IAM deployment user with path /deployment/, or adopts existing tagged user
  * @param client - IAMClient instance
  * @param userName - User name (format: {project}-{environment}-deploy)
- * @throws Error if user already exists or creation fails
+ * @throws Error if user exists but was not created by this tool
  */
-export declare function createDeploymentUser(client: IAMClient, userName: string): Promise<void>;
+export declare function createOrAdoptDeploymentUser(client: IAMClient, userName: string): Promise<void>;
+/**
+ * Legacy function for backward compatibility
+ * @deprecated Use createOrAdoptDeploymentUser instead
+ */
+export declare const createDeploymentUser: typeof createOrAdoptDeploymentUser;
 /**
  * Creates a customer managed policy with minimal CDK deployment permissions
  * @param client - IAMClient instance
@@ -48,11 +53,19 @@ export interface AccessKeyCredentials {
     accessKeyId: string;
     secretAccessKey: string;
 }
+/**
+ * Gets the count of access keys for an IAM user
+ * @param client - IAMClient instance
+ * @param userName - IAM user name
+ * @returns Number of access keys (active + inactive)
+ */
+export declare function getAccessKeyCount(client: IAMClient, userName: string): Promise<number>;
 /**
  * Creates access key credentials for an IAM user
  * @param client - IAMClient instance
  * @param userName - IAM user name
  * @returns Access key ID and secret access key
+ * @throws Error if user already has 2 access keys (AWS maximum)
  * @note The secret access key is ONLY available at creation time
  */
 export declare function createAccessKey(client: IAMClient, userName: string): Promise<AccessKeyCredentials>;

package/dist/aws/iam.js

@@ -1,4 +1,4 @@
-import { IAMClient, CreateUserCommand, GetUserCommand, CreatePolicyCommand, GetPolicyCommand, AttachUserPolicyCommand, CreateAccessKeyCommand, NoSuchEntityException, } from '@aws-sdk/client-iam';
+import { IAMClient, CreateUserCommand, GetUserCommand, CreatePolicyCommand, GetPolicyCommand, AttachUserPolicyCommand, CreateAccessKeyCommand, ListUserTagsCommand, ListAccessKeysCommand, NoSuchEntityException, } from '@aws-sdk/client-iam';
 import { fromTemporaryCredentials } from '@aws-sdk/credential-providers';
 import pc from 'picocolors';
 /**
@@ -73,16 +73,45 @@ async function policyExists(client, policyArn) {
     }
 }
 /**
- * Creates an IAM deployment user with path /deployment/
+ * Checks if an IAM user has a specific tag
+ * @param client - IAMClient instance
+ * @param userName - User name to check
+ * @param tagKey - Tag key to check for
+ * @param tagValue - Expected tag value
+ * @returns true if user has the tag with the specified value
+ */
+async function userHasTag(client, userName, tagKey, tagValue) {
+    try {
+        const command = new ListUserTagsCommand({ UserName: userName });
+        const response = await client.send(command);
+        return response.Tags?.some((tag) => tag.Key === tagKey && tag.Value === tagValue) ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Creates an IAM deployment user with path /deployment/, or adopts existing tagged user
  * @param client - IAMClient instance
  * @param userName - User name (format: {project}-{environment}-deploy)
- * @throws Error if user already exists or creation fails
+ * @throws Error if user exists but was not created by this tool
  */
-export async function createDeploymentUser(client, userName) {
+export async function createOrAdoptDeploymentUser(client, userName) {
     // Check if user already exists
     if (await userExists(client, userName)) {
-        throw new Error(`IAM user "${userName}" already exists. Delete manually before retrying.`);
+        // Check if user was created by this tool (has ManagedBy tag)
+        const isManagedByUs = await userHasTag(client, userName, 'ManagedBy', 'create-aws-starter-kit');
+        if (isManagedByUs) {
+            // Adopt existing user - this is idempotent re-run
+            console.log(pc.yellow(`  Adopting existing deployment user: ${userName}`));
+            return;
+        }
+        else {
+            // User exists but not managed by us - error
+            throw new Error(`IAM user "${userName}" exists but was not created by this tool. Delete it or use a different project name.`);
+        }
     }
+    // User doesn't exist - create it
     const command = new CreateUserCommand({
         UserName: userName,
         Path: '/deployment/',
@@ -94,6 +123,11 @@ export async function createDeploymentUser(client, userName) {
     await client.send(command);
     console.log(pc.green(`  Created IAM user: ${userName}`));
 }
+/**
+ * Legacy function for backward compatibility
+ * @deprecated Use createOrAdoptDeploymentUser instead
+ */
+export const createDeploymentUser = createOrAdoptDeploymentUser;
 /**
  * CDK deployment policy document with minimal permissions
  * @param accountId - AWS account ID for resource ARNs
@@ -226,14 +260,36 @@ export async function attachPolicyToUser(client, userName, policyArn) {
     await client.send(command);
     console.log(pc.green(`  Attached policy to user ${userName}`));
 }
+/**
+ * Gets the count of access keys for an IAM user
+ * @param client - IAMClient instance
+ * @param userName - IAM user name
+ * @returns Number of access keys (active + inactive)
+ */
+export async function getAccessKeyCount(client, userName) {
+    try {
+        const command = new ListAccessKeysCommand({ UserName: userName });
+        const response = await client.send(command);
+        return response.AccessKeyMetadata?.length ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
 /**
  * Creates access key credentials for an IAM user
  * @param client - IAMClient instance
  * @param userName - IAM user name
  * @returns Access key ID and secret access key
+ * @throws Error if user already has 2 access keys (AWS maximum)
  * @note The secret access key is ONLY available at creation time
  */
 export async function createAccessKey(client, userName) {
+    // Check access key limit before attempting creation
+    const keyCount = await getAccessKeyCount(client, userName);
+    if (keyCount >= 2) {
+        throw new Error(`IAM user ${userName} already has 2 access keys (AWS maximum). Delete an existing key in AWS Console > IAM > Users > ${userName} > Security credentials before retrying.`);
+    }
     const command = new CreateAccessKeyCommand({
         UserName: userName,
     });

package/dist/commands/initialize-github.js

@@ -10,7 +10,7 @@ import prompts from 'prompts';
 import pc from 'picocolors';
 import { execSync } from 'node:child_process';
 import { requireProjectContext } from '../utils/project-context.js';
-import { createCrossAccountIAMClient, createDeploymentUserWithCredentials, } from '../aws/iam.js';
+import { createCrossAccountIAMClient, createDeploymentUserWithCredentials, createAccessKey, } from '../aws/iam.js';
 import { createGitHubClient, setEnvironmentCredentials, parseGitHubUrl, } from '../github/secrets.js';
 const VALID_ENVIRONMENTS = ['dev', 'stage', 'prod'];
 /**
@@ -283,9 +283,24 @@ export async function runInitializeGitHub(args) {
         // Step 1: Create cross-account IAM client
         spinner.text = `Assuming role in ${env} account (${accountId})...`;
         const iamClient = createCrossAccountIAMClient(awsRegion, accountId);
-        // Step 2: Create deployment user and credentials
-        spinner.text = `Creating IAM deployment user...`;
-        const credentials = await createDeploymentUserWithCredentials(iamClient, projectName, env, accountId);
+        // Step 2: Get deployment user credentials
+        // If setup-aws-envs already created the user, just create an access key.
+        // Otherwise fall back to full user creation (backward compat with older projects).
+        const existingUserName = config.deploymentUsers?.[env];
+        let userName;
+        let credentials;
+        if (existingUserName) {
+            spinner.text = `Using existing deployment user: ${existingUserName}`;
+            userName = existingUserName;
+            credentials = await createAccessKey(iamClient, userName);
+            spinner.succeed(`Created access key for ${userName}`);
+        }
+        else {
+            spinner.text = `Creating IAM deployment user...`;
+            const fullCredentials = await createDeploymentUserWithCredentials(iamClient, projectName, env, accountId);
+            userName = fullCredentials.userName;
+            credentials = fullCredentials;
+        }
         // Step 3: Configure GitHub
         const githubEnvName = GITHUB_ENV_NAMES[env];
         spinner.text = `Configuring GitHub Environment "${githubEnvName}"...`;
@@ -297,8 +312,13 @@ export async function runInitializeGitHub(args) {
         console.log(pc.green(`${env} environment setup complete!`));
         console.log('');
         console.log('Resources created:');
-        console.log(`  IAM User: ${pc.cyan(`arn:aws:iam::${accountId}:user/deployment/${credentials.userName}`)}`);
+        console.log(`  Deployment User: ${pc.cyan(userName)}`);
         console.log(`  GitHub Environment: ${pc.cyan(githubEnvName)}`);
+        // Add note if using existing user from setup-aws-envs
+        if (existingUserName) {
+            console.log('');
+            console.log(pc.dim('Note: Deployment user was created by setup-aws-envs. Access key created for GitHub.'));
+        }
         console.log('');
         console.log('View secrets at:');
         console.log(`  ${pc.cyan(`https://github.com/${repoInfo.owner}/${repoInfo.repo}/settings/environments`)}`);

package/dist/commands/setup-aws-envs.js

@@ -10,6 +10,7 @@ import pc from 'picocolors';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { requireProjectContext } from '../utils/project-context.js';
 import { createOrganizationsClient, checkExistingOrganization, createOrganization, createAccount, waitForAccountCreation, } from '../aws/organizations.js';
+import { createCrossAccountIAMClient, createOrAdoptDeploymentUser, createCDKDeploymentPolicy, attachPolicyToUser, } from '../aws/iam.js';
 /**
  * Environment names for account creation
  */
@@ -101,14 +102,18 @@ async function collectEmails(projectName) {
     };
 }
 /**
- * Updates the config file with account IDs
+ * Updates the config file with account IDs and optionally deployment user names
  * @param configPath Path to the config file
  * @param accounts Record of environment to account ID
+ * @param deploymentUsers Optional record of environment to deployment user name
  */
-function updateConfigAccounts(configPath, accounts) {
+function updateConfig(configPath, accounts, deploymentUsers) {
     const content = readFileSync(configPath, 'utf-8');
     const config = JSON.parse(content);
     config.accounts = { ...config.accounts, ...accounts };
+    if (deploymentUsers) {
+        config.deploymentUsers = { ...config.deploymentUsers, ...deploymentUsers };
+    }
     writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
 }
 /**
@@ -174,14 +179,16 @@ export async function runSetupAwsEnvs(_args) {
     const { config, configPath } = context;
     // 2. Check if already configured (warn but don't abort - allows retry after partial failure)
     const existingAccounts = config.accounts ?? {};
+    const existingUsers = config.deploymentUsers ?? {};
     if (Object.keys(existingAccounts).length > 0) {
         console.log('');
         console.log(pc.yellow('Warning:') + ' AWS accounts already configured in this project:');
         for (const [env, id] of Object.entries(existingAccounts)) {
-            console.log(`  ${env}: ${id}`);
+            const userInfo = existingUsers[env] ? ` (user: ${existingUsers[env]})` : '';
+            console.log(`  ${env}: ${id}${userInfo}`);
         }
         console.log('');
-        console.log(pc.dim('Continuing will create additional accounts...'));
+        console.log(pc.dim('Continuing will skip existing accounts and create any missing ones...'));
     }
     // 3. Collect emails (all input before any AWS calls - per research pitfall #6)
     const emails = await collectEmails(config.projectName);
@@ -202,8 +209,13 @@ export async function runSetupAwsEnvs(_args) {
             spinner.succeed(`Using existing AWS Organization: ${orgId}`);
         }
         // Create accounts sequentially (per research - AWS rate limits require sequential)
-        const accounts = {};
+        const accounts = { ...existingAccounts };
         for (const env of ENVIRONMENTS) {
+            // Skip if account already exists
+            if (existingAccounts[env]) {
+                spinner.succeed(`Using existing ${env} account: ${existingAccounts[env]}`);
+                continue;
+            }
             spinner.start(`Creating ${env} account (this may take several minutes)...`);
             const accountName = `${config.projectName}-${env}`;
             const { requestId } = await createAccount(client, emails[env], accountName);
@@ -211,19 +223,42 @@ export async function runSetupAwsEnvs(_args) {
             const result = await waitForAccountCreation(client, requestId);
             accounts[env] = result.accountId;
             // Save after EACH successful account (per research pitfall #3 - handle partial success)
-            updateConfigAccounts(configPath, accounts);
+            updateConfig(configPath, accounts);
             spinner.succeed(`Created ${env} account: ${result.accountId}`);
         }
-        // Final success
+        // Create IAM deployment users in each account
+        const deploymentUsers = { ...existingUsers };
+        for (const env of ENVIRONMENTS) {
+            // Skip if user already exists in config
+            if (existingUsers[env]) {
+                spinner.succeed(`Using existing deployment user: ${existingUsers[env]}`);
+                continue;
+            }
+            const accountId = accounts[env];
+            const userName = `${config.projectName}-${env}-deploy`;
+            const policyName = `${config.projectName}-${env}-cdk-deploy`;
+            spinner.start(`Creating deployment user in ${env} account...`);
+            const iamClient = createCrossAccountIAMClient(config.awsRegion, accountId);
+            await createOrAdoptDeploymentUser(iamClient, userName);
+            spinner.text = `Creating deployment policy for ${env}...`;
+            const policyArn = await createCDKDeploymentPolicy(iamClient, policyName, accountId);
+            await attachPolicyToUser(iamClient, userName, policyArn);
+            deploymentUsers[env] = userName;
+            // Save after EACH successful user creation
+            updateConfig(configPath, accounts, deploymentUsers);
+            spinner.succeed(`Created deployment user: ${userName}`);
+        }
+        // Final success with summary table
         console.log('');
         console.log(pc.green('AWS environment setup complete!'));
         console.log('');
-        console.log('Account IDs saved to config:');
-        for (const [env, id] of Object.entries(accounts)) {
-            console.log(`  ${env}: ${id}`);
+        console.log('Summary:');
+        console.log(`  ${'Environment'.padEnd(14)}${'Account ID'.padEnd(16)}Deployment User`);
+        for (const env of ENVIRONMENTS) {
+            console.log(`  ${env.padEnd(14)}${accounts[env].padEnd(16)}${deploymentUsers[env]}`);
         }
         console.log('');
-        console.log(pc.bold('Next step:'));
+        console.log('Deployment users created. Next: initialize-github to create access keys and push to GitHub.');
         console.log(`  ${pc.cyan('npx create-aws-project initialize-github dev')}`);
     }
     catch (error) {

package/dist/utils/project-context.d.ts

@@ -19,6 +19,7 @@ export interface ProjectConfigMinimal {
     awsRegion: string;
     configVersion?: string;
     accounts?: Record<string, string>;
+    deploymentUsers?: Record<string, string>;
 }
 /**
  * Project context containing config path, project root, and parsed config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-aws-project",
-  "version": "1.4.3",
+  "version": "1.5.0",
   "description": "CLI tool to scaffold AWS projects",
   "type": "module",
   "main": "./dist/index.js",

package/templates/apps/api/cdk/static-stack.ts

@@ -3,7 +3,6 @@ import * as s3 from 'aws-cdk-lib/aws-s3';
 import * as cloudfront from 'aws-cdk-lib/aws-cloudfront';
 import * as origins from 'aws-cdk-lib/aws-cloudfront-origins';
 import * as apigateway from 'aws-cdk-lib/aws-apigateway';
-import * as opensearchserverless from 'aws-cdk-lib/aws-opensearchserverless';
 import { Construct } from 'constructs';
 
 export interface StaticStackProps extends cdk.StackProps {
@@ -24,7 +23,6 @@ export class StaticStack extends cdk.Stack {
   public readonly bucket: s3.Bucket;
   public readonly api: apigateway.RestApi;
   public readonly distribution: cloudfront.Distribution;
-  public readonly openSearchCollection: opensearchserverless.CfnCollection;
 
   constructor(scope: Construct, id: string, props: StaticStackProps) {
     super(scope, id, props);
@@ -205,94 +203,6 @@ export class StaticStack extends cdk.Stack {
       ],
     });
 
-    // OpenSearch Serverless Collection
-    const collectionName = `{{PROJECT_NAME}}-${environmentName}`;
-
-    // Encryption policy (required for all collections)
-    const encryptionPolicy = new opensearchserverless.CfnSecurityPolicy(this, 'OpenSearchEncryptionPolicy', {
-      name: `${collectionName}-encryption`,
-      type: 'encryption',
-      policy: JSON.stringify({
-        Rules: [
-          {
-            ResourceType: 'collection',
-            Resource: [`collection/${collectionName}`],
-          },
-        ],
-        AWSOwnedKey: true,
-      }),
-    });
-
-    // Network policy - allows public access (adjust for production)
-    const networkPolicy = new opensearchserverless.CfnSecurityPolicy(this, 'OpenSearchNetworkPolicy', {
-      name: `${collectionName}-network`,
-      type: 'network',
-      policy: JSON.stringify([
-        {
-          Rules: [
-            {
-              ResourceType: 'collection',
-              Resource: [`collection/${collectionName}`],
-            },
-            {
-              ResourceType: 'dashboard',
-              Resource: [`collection/${collectionName}`],
-            },
-          ],
-          AllowFromPublic: true,
-        },
-      ]),
-    });
-
-    // Data access policy - grants access to the collection
-    const dataAccessPolicy = new opensearchserverless.CfnAccessPolicy(this, 'OpenSearchDataAccessPolicy', {
-      name: `${collectionName}-access`,
-      type: 'data',
-      policy: JSON.stringify([
-        {
-          Rules: [
-            {
-              ResourceType: 'collection',
-              Resource: [`collection/${collectionName}`],
-              Permission: [
-                'aoss:CreateCollectionItems',
-                'aoss:DeleteCollectionItems',
-                'aoss:UpdateCollectionItems',
-                'aoss:DescribeCollectionItems',
-              ],
-            },
-            {
-              ResourceType: 'index',
-              Resource: [`index/${collectionName}/*`],
-              Permission: [
-                'aoss:CreateIndex',
-                'aoss:DeleteIndex',
-                'aoss:UpdateIndex',
-                'aoss:DescribeIndex',
-                'aoss:ReadDocument',
-                'aoss:WriteDocument',
-              ],
-            },
-          ],
-          Principal: [
-            `arn:aws:iam::${this.account}:root`,
-          ],
-        },
-      ]),
-    });
-
-    // Create the OpenSearch Serverless collection
-    this.openSearchCollection = new opensearchserverless.CfnCollection(this, 'OpenSearchCollection', {
-      name: collectionName,
-      type: 'SEARCH', // SEARCH, TIMESERIES, or VECTORSEARCH
-      description: `OpenSearch Serverless collection for {{PROJECT_NAME_TITLE}} - ${environmentName}`,
-    });
-
-    // Ensure policies are created before the collection
-    this.openSearchCollection.addDependency(encryptionPolicy);
-    this.openSearchCollection.addDependency(networkPolicy);
-    this.openSearchCollection.addDependency(dataAccessPolicy);
-
     // Output important values
     new cdk.CfnOutput(this, 'BucketName', {
       value: this.bucket.bucketName,
@@ -339,23 +249,5 @@ export class StaticStack extends cdk.Stack {
       value: `https://${this.distribution.distributionDomainName}/api`,
       description: 'API URL via CloudFront',
     });
-
-    new cdk.CfnOutput(this, 'OpenSearchCollectionEndpoint', {
-      value: this.openSearchCollection.attrCollectionEndpoint,
-      description: 'OpenSearch Serverless collection endpoint',
-      exportName: `${environmentName}-opensearch-endpoint`,
-    });
-
-    new cdk.CfnOutput(this, 'OpenSearchDashboardEndpoint', {
-      value: this.openSearchCollection.attrDashboardEndpoint,
-      description: 'OpenSearch Serverless dashboard endpoint',
-      exportName: `${environmentName}-opensearch-dashboard`,
-    });
-
-    new cdk.CfnOutput(this, 'OpenSearchCollectionArn', {
-      value: this.openSearchCollection.attrArn,
-      description: 'OpenSearch Serverless collection ARN',
-      exportName: `${environmentName}-opensearch-arn`,
-    });
   }
 }