Updated blog post with a deployable adapter example

Co-Authored-By: Claude <[email protected]>

Author: nyobe

content/blog/esc-connect/index.md

@@ -20,7 +20,7 @@ Pulumi ESC has [native integrations](/docs/esc/integrations/) with popular secre
 
 ESC Connect changes this by letting you build simple HTTPS adapter services using the [`external` provider](/docs/esc/integrations/dynamic-secrets/external/). Your adapter handles requests from ESC, fetches secrets from your custom source, and returns them. ESC handles authentication with signed JWT tokens, so you get fine-grained control over access without building a complete security infrastructure.
 
-## Building an Adapter
+## Building an adapter
 
 Here's an [ESC environment](/docs/esc/environments/) configuration that uses ESC Connect:
 
@@ -33,24 +33,71 @@ values:
         secretName: DATABASE_PASSWORD
 ```
 
-When you open this environment, ESC makes an authenticated POST request to your adapter. Your adapter validates the JWT token, fetches the secret from your source, and returns it:
+When you open this environment, ESC makes an authenticated POST request to your adapter. Your adapter validates the JWT token, fetches the secret from your source, and returns it.
+
+Here's a reusable validation helper you can copy into any adapter:
+
+```typescript
+class ESCRequestValidator {
+    private client: jwksClient.JwksClient;
+
+    constructor(jwksUrl: string = "https://api.pulumi.com/.well-known/jwks.json") {
+        this.client = jwksClient({
+            jwksUri: jwksUrl,
+            cache: true,
+            cacheMaxAge: 600000,
+        });
+    }
+
+    async validateRequest(event: APIGatewayProxyEvent): Promise<{
+        claims: jwt.JwtPayload;
+        requestBody: any;
+    }> {
+        // Extract and verify JWT from Authorization header
+        const authHeader = event.headers.Authorization || event.headers.authorization;
+        if (!authHeader?.startsWith("Bearer ")) {
+            throw new Error("Missing or invalid Authorization header");
+        }
+
+        const token = authHeader.substring(7);
+        const requestBody = event.body || "{}";
+
+        // Verify JWT signature using Pulumi's JWKS
+        const claims = await this.verifyJWT(token);
+
+        // Verify audience matches adapter URL
+        const requestUrl = `https://${event.headers.Host}${event.requestContext.path}`;
+        if (claims.aud !== requestUrl) {
+            throw new Error("Audience mismatch");
+        }
+
+        // Verify body hash to prevent replay attacks
+        if (!this.verifyBodyHash(requestBody, claims.body_hash)) {
+            throw new Error("Body hash verification failed");
+        }
+
+        return { claims, requestBody: JSON.parse(requestBody) };
+    }
+    // ... (additional helper methods)
+}
+```
+
+Use it in your adapter:
+
+```typescript
+const validator = new ESCRequestValidator();
 
-```python
-# Simplified example - see docs for complete implementation
-class AdapterHandler(BaseHTTPRequestHandler):
-    def do_POST(self):
-        # Verify JWT token from Authorization header
-        token = self.headers.get("Authorization", "").replace("Bearer ", "")
-        claims = verify_jwt(token)  # Validates signature, expiration, audience
+const handler = async (event: APIGatewayProxyEvent) => {
+    const { claims, requestBody } = await validator.validateRequest(event);
 
-        # Parse request and fetch secret
-        request = json.loads(self.rfile.read())
-        secret_value = fetch_from_your_source(request["secretName"])
+    // Fetch secret from your source
+    const secret = await fetchFromYourSource(requestBody.secretName);
 
-        # Return response
-        response = {"value": secret_value}
-        self.send_response(200)
-        self.wfile.write(json.dumps(response).encode())
+    return {
+        statusCode: 200,
+        body: JSON.stringify({ value: secret }),
+    };
+};
 ```
 
 Once deployed, the secrets become available in your ESC environment:
@@ -60,7 +107,7 @@ environmentVariables:
   DB_PASSWORD: ${customSecrets.response.value}
 ```
 
-The [documentation](/docs/esc/integrations/dynamic-secrets/external/) includes complete adapter examples with JWT verification, body hash validation, and security best practices.
+The [documentation](/docs/esc/integrations/dynamic-secrets/external/) includes a complete implementation with all helper methods and security best practices.
 
 ## Automated Rotation
 
@@ -79,8 +126,27 @@ values:
 
 The [rotation documentation](/docs/esc/integrations/rotated-secrets/external/) covers state management, dual-secret strategies, and implementation patterns.
 
-## Try It Out
+## Try it out
+
+ESC Connect is available now in Pulumi ESC. We've created a deployable reference implementation on AWS Lambda that you can use as a starting point:
+
+[![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-esc-external-adapter-lambda/README.md)
+
+The example includes the `ESCRequestValidator` class shown above and demonstrates:
+- JWT validation with Pulumi Cloud's JWKS
+- Request integrity checking with body hash verification
+- Inline Lambda deployment using Pulumi's function serialization
+- CloudWatch logging for debugging
+
+Deploy it with:
+
+```bash
+git clone https://github.com/pulumi/examples.git
+cd examples/aws-ts-esc-external-adapter-lambda
+npm install
+pulumi up
+```
 
-ESC Connect is available now in Pulumi ESC. Check out the documentation for the [external provider](/docs/esc/integrations/dynamic-secrets/external/) and [external rotation](/docs/esc/integrations/rotated-secrets/external/) to get started. The docs include complete adapter examples with JWT verification, security best practices, and example implementations in multiple languages.
+Check out the documentation for the [external provider](/docs/esc/integrations/dynamic-secrets/external/) and [external rotation](/docs/esc/integrations/rotated-secrets/external/) to learn more about building production adapters.
 
 To learn more about Pulumi ESC, explore the [ESC documentation](/docs/esc/) or [get started for free](/docs/esc/get-started/). If you build an adapter for a system that others might find useful, share it in the [Pulumi Community Slack](https://slack.pulumi.com) — we'd love to see what you build.