WIP

Author: nyobe

aws-ts-lambda-external-secrets/.gitignore

@@ -0,0 +1,2 @@
+/bin/
+/node_modules/

aws-ts-lambda-external-secrets/Pulumi.yaml

@@ -0,0 +1,3 @@
+name: aws-ts-lambda-external-secrets
+runtime: nodejs
+description: External secrets adapter for Pulumi ESC using AWS Lambda with JWT authentication

aws-ts-lambda-external-secrets/README.md

@@ -0,0 +1,339 @@
+[![Deploy this example with Pulumi](https://get.pulumi.com/new/button.svg)](https://app.pulumi.com/new?template=https://github.com/pulumi/examples/blob/master/aws-ts-lambda-external-secrets/README.md#gh-light-mode-only)
+[![Deploy this example with Pulumi](https://get.pulumi.com/new/button-light.svg)](https://app.pulumi.com/new?template=https://github.com/pulumi/examples/blob/master/aws-ts-lambda-external-secrets/README.md#gh-dark-mode-only)
+
+# External secrets adapter for Pulumi ESC on AWS Lambda
+
+An educational example demonstrating how to build a secure external secrets adapter for Pulumi ESC using AWS Lambda. This echo adapter validates JWT authentication and request integrity checking, serving as a reference implementation for custom integrations.
+
+## Overview
+
+This example shows how to integrate custom or proprietary secret sources with Pulumi ESC using the [external provider](/docs/esc/integrations/dynamic-secrets/external/). Instead of waiting for a native provider implementation, you can build your own HTTPS adapter service that:
+
+- Authenticates requests using JWT tokens issued by Pulumi Cloud
+- Verifies request integrity using SHA-256 body hashes
+- Returns secrets back to ESC in any format you choose
+
+This echo adapter demonstrates the security validation pattern without connecting to an actual secret store, making it an ideal starting point for building your own custom integrations.
+
+## What this example demonstrates
+
+- **JWT authentication**: Verifying RS256-signed tokens using Pulumi Cloud's JWKS endpoint
+- **Request integrity checking**: Validating SHA-256 SRI hashes to prevent replay attacks
+- **Secure HTTPS webhook endpoint**: API Gateway fronting a Lambda function
+- **Inline Lambda handler**: Using Pulumi's function serialization for simple deployment
+- **CloudWatch logging**: Server-side logging of JWT claims for debugging
+
+## Architecture
+
+This example provisions:
+
+- **AWS Lambda Function**: Executes the adapter validation logic (inline handler)
+- **Amazon API Gateway (REST)**: Provides public HTTPS endpoint
+- **IAM Role**: Grants Lambda permissions for CloudWatch Logs
+- **CloudWatch Logs**: Captures Lambda execution logs for monitoring
+
+The adapter validates requests from Pulumi ESC by:
+
+1. Extracting the JWT from the `Authorization` header
+2. Verifying the JWT signature against Pulumi Cloud's JWKS
+3. Checking the JWT audience claim matches the adapter URL
+4. Computing the request body hash and comparing it to the JWT's `body_hash` claim
+5. Echoing back the request with a timestamp (demonstrating successful validation)
+
+## Prerequisites
+
+- AWS account with appropriate permissions to create Lambda functions and API Gateway APIs
+- [Pulumi CLI](https://www.pulumi.com/docs/install/) installed
+- [Node.js](https://nodejs.org/) 18+ and npm
+- AWS credentials configured (via `aws configure` or environment variables)
+- [Pulumi ESC](https://www.pulumi.com/product/esc/) access (free tier available)
+
+## Deploying the adapter
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/pulumi/examples.git
+   cd examples/aws-ts-lambda-external-secrets
+   ```
+
+1. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+1. Create a new Pulumi stack:
+
+   ```bash
+   pulumi stack init dev
+   ```
+
+1. Configure your AWS region:
+
+   ```bash
+   pulumi config set aws:region us-west-2
+   ```
+
+1. Deploy the infrastructure:
+
+   ```bash
+   pulumi up
+   ```
+
+   Review the proposed changes and select "yes" to deploy.
+
+1. Note the adapter URL from the stack output:
+
+   ```bash
+   export ADAPTER_URL=$(pulumi stack output adapterUrl)
+   echo "Adapter URL: $ADAPTER_URL"
+   ```
+
+   The URL will look like: `https://abc123xyz.execute-api.us-west-2.amazonaws.com/stage/`
+
+## Using with Pulumi ESC
+
+Once deployed, create a Pulumi ESC environment to test the adapter:
+
+1. Create a new environment (via [Pulumi Cloud Console](https://app.pulumi.com/) or CLI):
+
+   ```bash
+   esc env init <your-org>/external-demo
+   ```
+
+1. Edit the environment definition:
+
+   ```yaml
+   values:
+     demo:
+       fn::open::external:
+         url: https://YOUR-API-ID.execute-api.us-west-2.amazonaws.com/stage/
+         request:
+           message: "Hello from ESC!"
+           environment: "production"
+   ```
+
+   Replace `YOUR-API-ID` with your actual API Gateway URL from the stack output.
+
+1. Open the environment to test the adapter:
+
+   ```bash
+   esc open <your-org>/external-demo
+   ```
+
+1. Expected output:
+
+   ```json
+   {
+     "demo": {
+       "response": {
+         "message": "External secrets adapter responding successfully!",
+         "requestEcho": {
+           "message": "Hello from ESC!",
+           "environment": "production"
+         },
+         "timestamp": "2025-11-26T12:00:00.000Z"
+       }
+     }
+   }
+   ```
+
+The response appears under `demo.response` and is automatically marked as secret by ESC (unless you set `secret: false` in the provider configuration).
+
+## What's happening under the hood
+
+When you open an ESC environment with an external provider, the following sequence occurs:
+
+1. **ESC generates JWT**: Pulumi ESC creates a signed JWT token containing:
+   - Your organization and environment identity
+   - The adapter URL as the audience (`aud` claim)
+   - SHA-256 hash of the request body (`body_hash` claim)
+   - Expiration time and other standard claims
+
+1. **ESC calls your adapter**: ESC makes an HTTPS POST request to your Lambda via API Gateway:
+   - `Authorization: Bearer <jwt-token>` header
+   - JSON body containing your `request` configuration
+
+1. **Lambda validates the request**:
+   - Extracts the JWT from the Authorization header
+   - Fetches Pulumi's public signing key from JWKS (`https://api.pulumi.com/.well-known/jwks.json`)
+   - Verifies the JWT signature using the RS256 algorithm
+   - Checks that the audience claim matches the adapter's URL
+   - Computes the SHA-256 hash of the request body
+   - Verifies the computed hash matches the `body_hash` claim in the JWT
+
+1. **Adapter responds**: If validation succeeds, the Lambda returns a JSON response that becomes available under `demo.response` in your ESC environment
+
+1. **ESC marks as secret**: By default, the entire response is marked as secret in ESC (shown as `[secret]` in output unless specifically accessed)
+
+## Monitoring and debugging
+
+View Lambda execution logs:
+
+```bash
+pulumi logs --follow
+```
+
+Or use the AWS CLI to tail CloudWatch Logs:
+
+```bash
+aws logs tail /aws/lambda/$(pulumi stack output functionName) --follow
+```
+
+The Lambda handler logs JWT claims to CloudWatch for debugging:
+
+```
+JWT validation successful
+Organization: acme-corp
+Environment: acme-corp/external-demo
+Trigger User: alice
+Issued At: 2025-11-26T12:00:00.000Z
+```
+
+### Common issues
+
+- **401 Unauthorized**: JWT signature verification failed. Check that the JWKS URL is correct and accessible.
+- **401 Audience mismatch**: The adapter URL in your ESC environment doesn't match the actual API Gateway URL. Verify the URL is exact (including trailing slash if present).
+- **400 Body hash verification failed**: The request body was modified in transit, or there's a bug in the hash computation. This should not happen in normal operation.
+- **500 Internal server error**: Check CloudWatch Logs for the specific error message.
+
+## Building your own adapter
+
+This example is intentionally simple (echo adapter). To integrate a real secret source:
+
+1. **Keep the security validation**: The JWT and body hash verification code is critical and should be preserved in any custom adapter.
+
+1. **Parse the request**: Extract parameters from the `request` body to determine which secrets to fetch:
+
+   ```typescript
+   const { secretName, environment } = request;
+   ```
+
+1. **Fetch secrets**: Call your proprietary API, database, or vault:
+
+   ```typescript
+   const secret = await fetchFromYourSecretStore(secretName, environment);
+   ```
+
+1. **Return secrets**: Format the response as a JSON object:
+
+   ```typescript
+   return {
+       statusCode: 200,
+       headers: { "Content-Type": "application/json" },
+       body: JSON.stringify({
+           username: secret.username,
+           password: secret.password,
+           endpoint: secret.endpoint,
+       }),
+   };
+   ```
+
+1. **Handle errors**: Return appropriate HTTP status codes:
+   - `200`: Success
+   - `401`: Authentication failure
+   - `400`: Validation failure or bad request
+   - `404`: Secret not found
+   - `500`: Internal error
+
+### Example modification for a real secret source
+
+Here's how you might modify the handler to fetch from an internal API:
+
+```typescript
+// After JWT validation succeeds...
+const { secretPath } = request;
+
+try {
+    // Call your internal API
+    const response = await fetch(`https://internal.example.com/secrets/${secretPath}`, {
+        headers: {
+            "Authorization": `Bearer ${process.env.INTERNAL_API_TOKEN}`,
+        },
+    });
+
+    if (!response.ok) {
+        return {
+            statusCode: response.status,
+            body: JSON.stringify({ error: "Failed to fetch secret" }),
+        };
+    }
+
+    const secret = await response.json();
+
+    return {
+        statusCode: 200,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            apiKey: secret.api_key,
+            apiSecret: secret.api_secret,
+        }),
+    };
+} catch (error) {
+    console.error("Error fetching secret:", error);
+    return {
+        statusCode: 500,
+        body: JSON.stringify({ error: "Internal server error" }),
+    };
+}
+```
+
+## Using with external rotator
+
+The external rotator works similarly to the external provider, but is designed for credential rotation. Here's a brief example:
+
+```yaml
+values:
+  rotatedCreds:
+    fn::rotate::external:
+      inputs:
+        url: https://YOUR-API-ID.execute-api.us-west-2.amazonaws.com/stage/
+        request:
+          service: my-api
+```
+
+Your rotator adapter receives:
+
+```json
+{
+  "request": { "service": "my-api" },
+  "state": null
+}
+```
+
+On the first rotation, `state` is `null`. On subsequent rotations, `state` contains the previous response. Your adapter should generate new credentials and return them:
+
+```json
+{
+  "apiKey": "newly-generated-key-123",
+  "rotatedAt": "2025-11-26T12:00:00Z"
+}
+```
+
+ESC stores this as the `current` state and passes it as `state` on the next rotation, allowing you to implement a two-secret rotation strategy for zero-downtime credential updates.
+
+See the [external rotator documentation](/docs/esc/integrations/rotated-secrets/external/) for details.
+
+## Clean up
+
+Remove all deployed resources:
+
+```bash
+pulumi destroy
+```
+
+Delete the stack:
+
+```bash
+pulumi stack rm dev
+```
+
+## Additional resources
+
+- [External Provider Documentation](/docs/esc/integrations/dynamic-secrets/external/)
+- [External Rotator Documentation](/docs/esc/integrations/rotated-secrets/external/)
+- [Pulumi ESC Documentation](/docs/esc/)
+- [Blog Post: Announcing External Provider and Rotator](/blog/esc-external-provider-rotator-launch/)
+- [Pulumi Community Slack](https://slack.pulumi.com/)
+- [ESC GitHub Issues](https://github.com/pulumi/esc/issues)