Under the hood

Architecture

A detailed look at how CloudLens works — from the Chrome extension manifest to the AWS SigV4 signing implementation, the Lambda proxy, and the security model that keeps your credentials safe.

High-level architecture

Overview

CloudLens is a Manifest V3 Chrome extension with three main components: a content script injected into AWS Console pages, a background service worker that handles all API calls, and a popup UI for settings and account summary. All three communicate via Chrome's message passing API.

The extension makes two types of external calls — directly to the AWS Cost Explorer API (SigV4-signed, using your IAM credentials) and to a Lambda proxy that forwards AI summary requests to the Anthropic Claude API. Your credentials and cost data never reach CloudLens servers.

manifest.json

Declares permissions, host_permissions, content script rules, service worker, and popup action. Manifest V3 required for all new Chrome Web Store listings.

service-worker.js

Message router. Handles GET_ACCOUNT_SUMMARY, GET_AI_SUMMARY, CREDENTIALS_SAVED, and the weekly Monday digest alarm.

aws-client.js

Cost Explorer API client with hand-rolled SigV4 signing using the Web Crypto API. No AWS SDK — keeps the bundle under 50KB.

claude-client.js

Sends anonymised cost data to the Lambda proxy. Returns plain-English AI summaries for the badge tooltip.

injector.js

Content script. Watches for AWS Console URL changes every 600ms, parses resource type from URL pattern, injects cost badge into the page DOM.

cache.js

TTL cache using chrome.storage.session. Cost data cached 4 hours, AI summaries 24 hours. Avoids hammering the Cost Explorer API on every page load.

Manifest V3 — key design decisions

MV3 replaces persistent background pages with service workers — ephemeral processes that spin down when idle and wake on demand. This has three important implications:

No global state. Everything persistent goes through chrome.storage — never in-memory variables that reset when the worker terminates.
Alarms instead of timers. The weekly digest uses chrome.alarms rather than setInterval, which wouldn't survive worker termination.
Minimal permissions. MV3 requires explicit host_permissions for every domain the extension communicates with. CloudLens declares only the AWS Console, Cost Explorer API, and the Lambda proxy endpoint.

AWS SigV4 signing — no SDK

The Cost Explorer API requires every request to be signed using AWS Signature Version 4. Rather than bundling the AWS SDK (which adds ~3MB), CloudLens implements SigV4 signing using the browser's native Web Crypto API, available in service workers.

Canonical request

Sort and lowercase headers, SHA-256 hash the request body, build a canonical string from method, path, headers, and body hash.

String to sign

Combine algorithm identifier, timestamp, credential scope (date/region/service), and the hash of the canonical request.

Signing key derivation

HMAC chain using the secret key: AWS4+secret → date → region → service → aws4_request. Each step adds specificity to the key.

Final signature

HMAC-SHA256 of the string-to-sign with the derived key, hex-encoded. Added to the Authorization header on every request.

IAM policy

CloudLens requires a dedicated IAM user with this minimal read-only policy. It cannot access any service data — only billing records.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "ce:GetCostAndUsage",
      "ce:GetCostAndUsageWithResources",
      "ce:GetDimensionValues",
      "ce:GetCostForecast"
    ],
    "Resource": "*"
  }]
}

Lambda proxy for Claude API

Chrome extensions cannot call the Anthropic API directly due to CORS restrictions. CloudLens routes AI summary requests through a Lambda function deployed via CloudFormation.

API Gateway receives POST requests from the extension over HTTPS
Lambda reads the Claude API key from SSM Parameter Store at cold start and caches it in memory
Lambda forwards the request to api.anthropic.com/v1/messages
Response is returned to the extension with CORS headers added
The proxy logs only model name and timestamp — never cost data, credentials, or API keys

Data flow and privacy

IAM credentials — stored in chrome.storage.local (encrypted at rest). Transmitted only to ce.us-east-1.amazonaws.com. Never sent to CloudLens servers.
Cost data — returned from AWS, cached in chrome.storage.session (cleared on browser close). Never sent to CloudLens servers.
AI summary requests — dollar amounts and service names only. No account IDs, resource ARNs, or identifiers. Sent to Lambda proxy, forwarded to Anthropic.
Claude API key — stored in chrome.storage.local. Transmitted to the Lambda proxy only, which forwards it to Anthropic without logging it.

Supported AWS Console URL patterns

The content script watches for URL changes every 600ms and maps them to resource types:

/ec2/ — EC2 instances, EBS volumes, load balancers
/s3/ — S3 buckets
/rds/ — RDS databases and Aurora clusters
/lambda/ — Lambda functions
/dynamodb/ — DynamoDB tables
/ecs/ — ECS clusters and services
/cloudfront/ — CloudFront distributions
/cost-management/ — Account billing total