@phila/cli 0.0.17 → 0.0.18

package/dist/templates/lambda-api-nodejs/README.md.tmpl

@@ -83,6 +83,51 @@ Or use the City CLI:
 city config list --env dev
 ```
 
+## API Authentication
+
+The API uses path-based authentication with two endpoint patterns:
+
+| Path Pattern | Authentication | Use Case |
+|--------------|----------------|----------|
+| `/public/*` | None | Health checks, public data, webhooks |
+| `/private/key/*` | API Key required | Protected endpoints |
+
+### Using Protected Endpoints
+
+Protected endpoints require the `x-api-key` header. The API key is stored in AWS Secrets Manager and encrypted with a dedicated KMS key.
+
+**Retrieve the API key:**
+
+```bash
+# Get the secret ARN from Parameter Store
+SECRET_ARN=$(aws ssm get-parameter \
+  --name "/dev/{{appName}}/api/main/key-secret-arn" \
+  --query Parameter.Value --output text)
+
+# Retrieve the API key value
+API_KEY=$(aws secretsmanager get-secret-value \
+  --secret-id "$SECRET_ARN" \
+  --query SecretString --output text)
+```
+
+**Call a protected endpoint:**
+
+```bash
+curl -H "x-api-key: $API_KEY" \
+  "https://<api-id>.execute-api.us-east-1.amazonaws.com/dev/private/key/items"
+```
+
+### API Key Rotation
+
+API keys are **not** automatically rotated. When you need to rotate:
+
+1. Generate a new secret value in Secrets Manager
+2. Update the API Gateway API key
+3. Coordinate with all API consumers to update their keys
+4. Delete the old API key after migration
+
+This manual approach ensures controlled rollover without breaking existing integrations.
+
 ## Routing with philaroute
 
 This template uses [@phila/philaroute](https://www.npmjs.com/package/@phila/philaroute) for HTTP routing. Routes are defined using a composable pipeline pattern.
@@ -179,12 +224,15 @@ To add a database to your API:
 ## Resources Created
 
 This application creates:
-- **API Gateway REST API** - HTTP endpoint for your application
+- **API Gateway REST API** - HTTP endpoint with path-based auth
+- **API Key & Usage Plan** - For protected endpoint authentication
+- **Secrets Manager Secret** - Stores API key (KMS encrypted)
+- **KMS Key** - Encrypts the API key secret (auto-rotates annually)
+- **WAF Web ACL** - Protects API from common attacks
 - **Lambda Function** - Serverless compute for handling requests
-- **VPC Security Group** - Network security for Lambda
 - **IAM Role** - Permissions for Lambda execution
-- **SSM Parameters** - Resource discovery (API URL, Lambda ARN)
-- **CloudWatch Logs** - Application logs
+- **SSM Parameters** - Resource discovery (API URL, API key secret ARN)
+- **CloudWatch Logs** - Application and API Gateway access logs
 
 ## Next Steps
 

package/dist/templates/lambda-dynamo-api/README.md.tmpl

@@ -83,6 +83,51 @@ Or use the City CLI:
 city config list --env dev
 ```
 
+## API Authentication
+
+The API uses path-based authentication with two endpoint patterns:
+
+| Path Pattern | Authentication | Use Case |
+|--------------|----------------|----------|
+| `/public/*` | None | Health checks, public data, webhooks |
+| `/private/key/*` | API Key required | Protected endpoints |
+
+### Using Protected Endpoints
+
+Protected endpoints require the `x-api-key` header. The API key is stored in AWS Secrets Manager and encrypted with a dedicated KMS key.
+
+**Retrieve the API key:**
+
+```bash
+# Get the secret ARN from Parameter Store
+SECRET_ARN=$(aws ssm get-parameter \
+  --name "/dev/{{appName}}/api/main/key-secret-arn" \
+  --query Parameter.Value --output text)
+
+# Retrieve the API key value
+API_KEY=$(aws secretsmanager get-secret-value \
+  --secret-id "$SECRET_ARN" \
+  --query SecretString --output text)
+```
+
+**Call a protected endpoint:**
+
+```bash
+curl -H "x-api-key: $API_KEY" \
+  "https://<api-id>.execute-api.us-east-1.amazonaws.com/dev/private/key/items"
+```
+
+### API Key Rotation
+
+API keys are **not** automatically rotated. When you need to rotate:
+
+1. Generate a new secret value in Secrets Manager
+2. Update the API Gateway API key
+3. Coordinate with all API consumers to update their keys
+4. Delete the old API key after migration
+
+This manual approach ensures controlled rollover without breaking existing integrations.
+
 ## DynamoDB Operations
 
 The template includes example CRUD operations using AWS SDK v3:
@@ -159,13 +204,16 @@ The default table uses a single partition key (`pk`). To modify:
 ## Resources Created
 
 This application creates:
-- **API Gateway REST API** - HTTP endpoint for your application
+- **API Gateway REST API** - HTTP endpoint with path-based auth
+- **API Key & Usage Plan** - For protected endpoint authentication
+- **Secrets Manager Secret** - Stores API key (KMS encrypted)
+- **KMS Key** - Encrypts the API key secret (auto-rotates annually)
+- **WAF Web ACL** - Protects API from common attacks
 - **Lambda Function** - Serverless compute for handling requests
 - **DynamoDB Table** - NoSQL database with pay-per-request billing
-- **VPC Security Group** - Network security for Lambda
 - **IAM Role** - Permissions for Lambda execution (DynamoDB read/write)
-- **SSM Parameters** - Resource discovery (API URL, Table Name, Lambda ARN)
-- **CloudWatch Logs** - Application logs
+- **SSM Parameters** - Resource discovery (API URL, Table Name, API key secret ARN)
+- **CloudWatch Logs** - Application and API Gateway access logs
 
 ## Next Steps
 

package/dist/templates/lambda-postgres-api/README.md.tmpl

@@ -83,6 +83,51 @@ Or use the City CLI:
 city config list --env dev
 ```
 
+## API Authentication
+
+The API uses path-based authentication with two endpoint patterns:
+
+| Path Pattern | Authentication | Use Case |
+|--------------|----------------|----------|
+| `/public/*` | None | Health checks, public data, webhooks |
+| `/private/key/*` | API Key required | Protected endpoints |
+
+### Using Protected Endpoints
+
+Protected endpoints require the `x-api-key` header. The API key is stored in AWS Secrets Manager and encrypted with a dedicated KMS key.
+
+**Retrieve the API key:**
+
+```bash
+# Get the secret ARN from Parameter Store
+SECRET_ARN=$(aws ssm get-parameter \
+  --name "/dev/{{appName}}/api/main/key-secret-arn" \
+  --query Parameter.Value --output text)
+
+# Retrieve the API key value
+API_KEY=$(aws secretsmanager get-secret-value \
+  --secret-id "$SECRET_ARN" \
+  --query SecretString --output text)
+```
+
+**Call a protected endpoint:**
+
+```bash
+curl -H "x-api-key: $API_KEY" \
+  "https://<api-id>.execute-api.us-east-1.amazonaws.com/dev/private/key/items"
+```
+
+### API Key Rotation
+
+API keys are **not** automatically rotated. When you need to rotate:
+
+1. Generate a new secret value in Secrets Manager
+2. Update the API Gateway API key
+3. Coordinate with all API consumers to update their keys
+4. Delete the old API key after migration
+
+This manual approach ensures controlled rollover without breaking existing integrations.
+
 ## Routing with philaroute
 
 This template uses [@phila/philaroute](https://www.npmjs.com/package/@phila/philaroute) for HTTP routing. Routes are defined using a composable pipeline pattern.
@@ -191,14 +236,17 @@ Lambda functions automatically receive:
 ## Resources Created
 
 This application creates:
-- **API Gateway REST API** - HTTP endpoint for your application
+- **API Gateway REST API** - HTTP endpoint with path-based auth
+- **API Key & Usage Plan** - For protected endpoint authentication
+- **Secrets Manager Secrets** - API key and database credentials (KMS encrypted)
+- **KMS Keys** - Encrypts API key and database secrets (auto-rotate annually)
+- **WAF Web ACL** - Protects API from common attacks
 - **Lambda Function** - Serverless compute for handling requests
 - **RDS PostgreSQL** - Managed database instance
-- **Secrets Manager Secret** - Database credentials
 - **VPC Security Groups** - Network security for Lambda and database
-- **IAM Roles** - Permissions for Lambda and database access
-- **SSM Parameters** - Resource discovery (API URL, database endpoint)
-- **CloudWatch Logs** - Application logs
+- **IAM Roles** - Permissions for Lambda, Secrets Manager, and database access
+- **SSM Parameters** - Resource discovery (API URL, API key secret ARN, database endpoint)
+- **CloudWatch Logs** - Application and API Gateway access logs
 
 ## Serverless Aurora
 

package/dist/templates/webapp-lambda-dotnet/README.md.tmpl

@@ -112,6 +112,27 @@ This automatically creates a route at `/about`.
 
 The API uses [.NET Minimal API](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis) with AWS Lambda hosting.
 
+### Authentication
+
+The API uses path-based authentication:
+
+| Path Pattern | Authentication | Use Case |
+|--------------|----------------|----------|
+| `/public/*` | None | Health checks, public data |
+| `/private/key/*` | API Key required | Protected endpoints |
+
+**Retrieve the API key:**
+
+```bash
+SECRET_ARN=$(aws ssm get-parameter \
+  --name "/dev/{{appName}}/api/main/key-secret-arn" \
+  --query Parameter.Value --output text)
+API_KEY=$(aws secretsmanager get-secret-value \
+  --secret-id "$SECRET_ARN" --query SecretString --output text)
+```
+
+The API key is stored in Secrets Manager, encrypted with a dedicated KMS key. Keys are not auto-rotated; coordinate manual rotation with API consumers.
+
 ### Adding Endpoints
 
 Edit `apps/api/Program.cs`:
@@ -152,15 +173,17 @@ This application creates:
 - **Origin Access Control** - Secure S3 access
 
 **API:**
-- **API Gateway REST API** - HTTP endpoint
+- **API Gateway REST API** - HTTP endpoint with path-based auth
+- **API Key & Usage Plan** - For protected endpoint authentication
+- **Secrets Manager Secret** - Stores API key (KMS encrypted)
+- **WAF Web ACL** - Protects API from common attacks
 - **Lambda Function** - .NET 8 serverless compute
-- **VPC Security Group** - Network security
 - **IAM Role** - Permissions for Lambda execution
 
 **Shared:**
-- **SSM Parameters** - Resource discovery
-- **CloudWatch Logs** - Application logs
-- **KMS Keys** - Encryption
+- **SSM Parameters** - Resource discovery (URLs, API key secret ARN)
+- **CloudWatch Logs** - Application and API access logs
+- **KMS Keys** - Encryption for secrets
 
 ## URLs
 

package/dist/templates/webapp-lambda-dynamo-dotnet/README.md.tmpl

@@ -112,6 +112,27 @@ This automatically creates a route at `/about`.
 
 The API uses [.NET Minimal API](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis) with AWS Lambda hosting and DynamoDB.
 
+### Authentication
+
+The API uses path-based authentication:
+
+| Path Pattern | Authentication | Use Case |
+|--------------|----------------|----------|
+| `/public/*` | None | Health checks, public data |
+| `/private/key/*` | API Key required | Protected endpoints |
+
+**Retrieve the API key:**
+
+```bash
+SECRET_ARN=$(aws ssm get-parameter \
+  --name "/dev/{{appName}}/api/main/key-secret-arn" \
+  --query Parameter.Value --output text)
+API_KEY=$(aws secretsmanager get-secret-value \
+  --secret-id "$SECRET_ARN" --query SecretString --output text)
+```
+
+The API key is stored in Secrets Manager, encrypted with a dedicated KMS key. Keys are not auto-rotated; coordinate manual rotation with API consumers.
+
 ### Adding Endpoints
 
 Edit `apps/api/Program.cs`:
@@ -191,16 +212,18 @@ This application creates:
 - **Origin Access Control** - Secure S3 access
 
 **API:**
-- **API Gateway REST API** - HTTP endpoint
+- **API Gateway REST API** - HTTP endpoint with path-based auth
+- **API Key & Usage Plan** - For protected endpoint authentication
+- **Secrets Manager Secret** - Stores API key (KMS encrypted)
+- **WAF Web ACL** - Protects API from common attacks
 - **Lambda Function** - .NET 8 serverless compute
 - **DynamoDB Table** - NoSQL database
-- **VPC Security Group** - Network security
 - **IAM Role** - Permissions for Lambda and DynamoDB
 
 **Shared:**
-- **SSM Parameters** - Resource discovery
-- **CloudWatch Logs** - Application logs
-- **KMS Keys** - Encryption
+- **SSM Parameters** - Resource discovery (URLs, API key secret ARN)
+- **CloudWatch Logs** - Application and API access logs
+- **KMS Keys** - Encryption for secrets and DynamoDB
 
 ## URLs
 

package/dist/templates/webapp-lambda-dynamo-node/README.md.tmpl

@@ -110,6 +110,27 @@ This automatically creates a route at `/about`.
 
 The API uses [@phila/philaroute](https://www.npmjs.com/package/@phila/philaroute) for HTTP routing with DynamoDB for data persistence.
 
+### Authentication
+
+The API uses path-based authentication:
+
+| Path Pattern | Authentication | Use Case |
+|--------------|----------------|----------|
+| `/public/*` | None | Health checks, public data |
+| `/private/key/*` | API Key required | Protected endpoints |
+
+**Retrieve the API key:**
+
+```bash
+SECRET_ARN=$(aws ssm get-parameter \
+  --name "/dev/{{appName}}/api/main/key-secret-arn" \
+  --query Parameter.Value --output text)
+API_KEY=$(aws secretsmanager get-secret-value \
+  --secret-id "$SECRET_ARN" --query SecretString --output text)
+```
+
+The API key is stored in Secrets Manager, encrypted with a dedicated KMS key. Keys are not auto-rotated; coordinate manual rotation with API consumers.
+
 ### DynamoDB Operations
 
 The template includes CRUD operations in `apps/api/index.ts`:
@@ -157,16 +178,18 @@ This application creates:
 - **Origin Access Control** - Secure S3 access
 
 **API:**
-- **API Gateway REST API** - HTTP endpoint
+- **API Gateway REST API** - HTTP endpoint with path-based auth
+- **API Key & Usage Plan** - For protected endpoint authentication
+- **Secrets Manager Secret** - Stores API key (KMS encrypted)
+- **WAF Web ACL** - Protects API from common attacks
 - **Lambda Function** - Serverless compute
 - **DynamoDB Table** - NoSQL database with encryption
-- **VPC Security Group** - Network security
 - **IAM Role** - Permissions for Lambda and DynamoDB
 
 **Shared:**
-- **SSM Parameters** - Resource discovery
-- **CloudWatch Logs** - Application logs
-- **KMS Keys** - Encryption
+- **SSM Parameters** - Resource discovery (URLs, API key secret ARN)
+- **CloudWatch Logs** - Application and API access logs
+- **KMS Keys** - Encryption for secrets and DynamoDB
 
 ## URLs
 

package/dist/templates/webapp-lambda-node/README.md.tmpl

@@ -110,6 +110,27 @@ This automatically creates a route at `/about`.
 
 The API uses [@phila/philaroute](https://www.npmjs.com/package/@phila/philaroute) for HTTP routing.
 
+### Authentication
+
+The API uses path-based authentication:
+
+| Path Pattern | Authentication | Use Case |
+|--------------|----------------|----------|
+| `/public/*` | None | Health checks, public data |
+| `/private/key/*` | API Key required | Protected endpoints |
+
+**Retrieve the API key:**
+
+```bash
+SECRET_ARN=$(aws ssm get-parameter \
+  --name "/dev/{{appName}}/api/main/key-secret-arn" \
+  --query Parameter.Value --output text)
+API_KEY=$(aws secretsmanager get-secret-value \
+  --secret-id "$SECRET_ARN" --query SecretString --output text)
+```
+
+The API key is stored in Secrets Manager, encrypted with a dedicated KMS key. Keys are not auto-rotated; coordinate manual rotation with API consumers.
+
 ### Adding Endpoints
 
 Edit `apps/api/index.ts`:
@@ -143,15 +164,17 @@ This application creates:
 - **Origin Access Control** - Secure S3 access
 
 **API:**
-- **API Gateway REST API** - HTTP endpoint
+- **API Gateway REST API** - HTTP endpoint with path-based auth
+- **API Key & Usage Plan** - For protected endpoint authentication
+- **Secrets Manager Secret** - Stores API key (KMS encrypted)
+- **WAF Web ACL** - Protects API from common attacks
 - **Lambda Function** - Serverless compute
-- **VPC Security Group** - Network security
 - **IAM Role** - Permissions for Lambda execution
 
 **Shared:**
-- **SSM Parameters** - Resource discovery
-- **CloudWatch Logs** - Application logs
-- **KMS Keys** - Encryption
+- **SSM Parameters** - Resource discovery (URLs, API key secret ARN)
+- **CloudWatch Logs** - Application and API access logs
+- **KMS Keys** - Encryption for secrets
 
 ## URLs
 

package/dist/templates/webapp-lambda-postgres-dotnet/README.md.tmpl

@@ -112,6 +112,27 @@ This automatically creates a route at `/about`.
 
 The API uses [.NET Minimal API](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis) with AWS Lambda hosting and PostgreSQL via Npgsql.
 
+### Authentication
+
+The API uses path-based authentication:
+
+| Path Pattern | Authentication | Use Case |
+|--------------|----------------|----------|
+| `/public/*` | None | Health checks, public data |
+| `/private/key/*` | API Key required | Protected endpoints |
+
+**Retrieve the API key:**
+
+```bash
+SECRET_ARN=$(aws ssm get-parameter \
+  --name "/dev/{{appName}}/api/main/key-secret-arn" \
+  --query Parameter.Value --output text)
+API_KEY=$(aws secretsmanager get-secret-value \
+  --secret-id "$SECRET_ARN" --query SecretString --output text)
+```
+
+The API key is stored in Secrets Manager, encrypted with a dedicated KMS key. Keys are not auto-rotated; coordinate manual rotation with API consumers.
+
 ### Adding Endpoints
 
 Edit `apps/api/Program.cs`:
@@ -207,17 +228,19 @@ This application creates:
 - **Origin Access Control** - Secure S3 access
 
 **API:**
-- **API Gateway REST API** - HTTP endpoint
+- **API Gateway REST API** - HTTP endpoint with path-based auth
+- **API Key & Usage Plan** - For protected endpoint authentication
+- **Secrets Manager Secrets** - API key and database credentials (KMS encrypted)
+- **WAF Web ACL** - Protects API from common attacks
 - **Lambda Function** - .NET 8 serverless compute
 - **RDS PostgreSQL** - Relational database
-- **Secrets Manager** - Database credentials
 - **VPC Security Group** - Network security
-- **IAM Role** - Permissions for Lambda and database
+- **IAM Role** - Permissions for Lambda, Secrets Manager, and database
 
 **Shared:**
-- **SSM Parameters** - Resource discovery
-- **CloudWatch Logs** - Application logs
-- **KMS Keys** - Encryption
+- **SSM Parameters** - Resource discovery (URLs, API key secret ARN)
+- **CloudWatch Logs** - Application and API access logs
+- **KMS Keys** - Encryption for secrets
 
 ## URLs
 

package/dist/templates/webapp-lambda-postgres-node/README.md.tmpl

@@ -110,6 +110,27 @@ This automatically creates a route at `/about`.
 
 The API uses [@phila/philaroute](https://www.npmjs.com/package/@phila/philaroute) for HTTP routing with PostgreSQL for data persistence.
 
+### Authentication
+
+The API uses path-based authentication:
+
+| Path Pattern | Authentication | Use Case |
+|--------------|----------------|----------|
+| `/public/*` | None | Health checks, public data |
+| `/private/key/*` | API Key required | Protected endpoints |
+
+**Retrieve the API key:**
+
+```bash
+SECRET_ARN=$(aws ssm get-parameter \
+  --name "/dev/{{appName}}/api/main/key-secret-arn" \
+  --query Parameter.Value --output text)
+API_KEY=$(aws secretsmanager get-secret-value \
+  --secret-id "$SECRET_ARN" --query SecretString --output text)
+```
+
+The API key is stored in Secrets Manager, encrypted with a dedicated KMS key. Keys are not auto-rotated; coordinate manual rotation with API consumers.
+
 ### Database Setup
 
 1. Install a PostgreSQL client:
@@ -157,17 +178,19 @@ This application creates:
 - **Origin Access Control** - Secure S3 access
 
 **API:**
-- **API Gateway REST API** - HTTP endpoint
+- **API Gateway REST API** - HTTP endpoint with path-based auth
+- **API Key & Usage Plan** - For protected endpoint authentication
+- **Secrets Manager Secrets** - API key and database credentials (KMS encrypted)
+- **WAF Web ACL** - Protects API from common attacks
 - **Lambda Function** - Serverless compute in VPC
 - **RDS PostgreSQL** - Managed relational database
-- **Secrets Manager Secret** - Database credentials
 - **VPC Security Groups** - Network security for Lambda and RDS
 - **IAM Role** - Permissions for Lambda and Secrets Manager
 
 **Shared:**
-- **SSM Parameters** - Resource discovery
-- **CloudWatch Logs** - Application logs
-- **KMS Keys** - Encryption
+- **SSM Parameters** - Resource discovery (URLs, API key secret ARN)
+- **CloudWatch Logs** - Application and API access logs
+- **KMS Keys** - Encryption for secrets
 
 ## URLs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phila/cli",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "description": "CLI tool for City of Philadelphia AWS infrastructure",
   "main": "dist/index.js",
   "bin": {
@@ -24,7 +24,7 @@
     "commander": "^11.0.0",
     "fs-extra": "^11.1.0",
     "inquirer": "^8.2.5",
-    "@phila/constructs": "0.0.10",
+    "@phila/constructs": "0.0.11",
     "@phila/db-postgres": "0.0.6"
   },
   "devDependencies": {