raindancers-cloudfront 0.0.3 → 0.0.4

package/README.md

@@ -1,176 +1,115 @@
-# DevContainer Setup.
+# The CDN Is Already a Zero Trust Gateway
 
-This directory contains the configuration and setup scripts for the development container environment.
+Many organisations are buying, evaluating, or already paying for zero trust network access (ZTNA) overlay products. These are tools that sit in front of your workloads, verify identity, enforce policy, and only then allow traffic through.
 
-## Overview
+I've implemented them into several environments, and it made me think about what they're really doing at the fundamental layer.
 
-The devcontainer is based on the TypeScript/Node.js 22 image and includes AWS development tools, Python, and Docker support.
+Here's the thing — if you're running web applications behind a CDN, you already have that enforcement point.
 
-## WSL2 Setup for Optimal Performance
+## What Zero Trust Actually Means at the Edge
 
-**Recommended**: Clone and work with this repository directly in WSL2 for significantly better performance (5-10x faster than Windows filesystem access).
+Zero trust, stripped of the marketing, means: don't trust the network. Verify every request. Enforce policy as close to the requester as possible.
 
-### Prerequisites
-- Windows 10/11 with WSL2 enabled
-- Docker Desktop for Windows with WSL2 backend enabled
-- VS Code with Remote Development extension pack installed
+A CDN edge node is, by definition, the closest compute to the requester. Every major CDN provider now offers programmable compute at the edge — AWS CloudFront has CloudFront Functions and Lambda@Edge, Cloudflare has Workers, Azure has Azure Front Door with Rules Engine and Azure Functions integration.
 
-### Setup Steps
+That means you can verify identity, validate tokens, check session state, and enforce access policy *before a single byte reaches your origin infrastructure*. Not at the load balancer. Not at the API gateway. At the edge, milliseconds from the user.
 
-1. **Open a WSL2 terminal** (e.g., Ubuntu from Windows Terminal)
+That's zero trust enforcement. It's included in the price of your CDN.
 
-2. **Clone the repository in WSL2 filesystem**:
-   ```bash
-   cd ~
-   git clone <repository-url>
-   cd cdk-api
-   ```
+## The Architecture
 
-3. **Open in VS Code**:
-   ```bash
-   code .
-   ```
-   
-4. **Reopen in Container**: When prompted by VS Code, click "Reopen in Container"
-   - Or use Command Palette: `Dev Containers: Reopen in Container`
+Let me walk through what this looks like on AWS CloudFront, since that's where I've built a working implementation. The same principles apply to Cloudflare and Azure Front Door.
 
-### GitHub CLI Setup
+```mermaid
+sequenceDiagram
+    participant User
+    participant WAF
+    participant CF as CloudFront Function
+    participant KVS as KeyValueStore
+    participant Edge as Lambda@Edge
+    participant Origin
 
-If you need to clone private repositories or authenticate with GitHub from within WSL2, you may need to install GitHub CLI:
+    User->>WAF: Request
+    Note over WAF: Rate limiting<br/>Geo-blocking<br/>Bot detection<br/>IP reputation
 
-1. **Open Windows Terminal and access your WSL2 distro as root**:
-   ```bash
-   wsl -u root
-   ```
+    WAF->>CF: Allowed request
+    CF->>KVS: Check session revocation
+    KVS-->>CF: Session status
 
-2. **Install GitHub CLI**:
-   ```bash
-   apt update && apt install gh
-   ```
-
-3. **Exit root and authenticate** (as your regular user):
-   ```bash
-   exit
-   gh auth login
-   ```
-   
-   Follow the prompts and select:
-   - **GitHub.com**
-   - **HTTPS** protocol
-   - **Login with a web browser** (device code flow)
-   - Copy the one-time code and press Enter to open the browser
-   - Paste the code in GitHub to complete authentication
-
-**Note**: This installs `gh` in your WSL2 distro, not in the devcontainer. The devcontainer will inherit your WSL2 git credentials when cloning repositories.
-
-### Verify Your Setup
+    alt Session valid
+        CF->>Origin: Forward request
+        Origin-->>User: Response
+    else Session invalid or missing
+        CF->>Edge: Auth required
+        Note over Edge: JWT validation<br/>OAuth token exchange<br/>Session establishment<br/>HMAC verification
+        Edge-->>User: Redirect to IdP / Set session cookie
+    end
+```
 
-To confirm you're running with optimal performance:
+The architecture uses layers, each doing what it's best at:
 
-```bash
-# Check filesystem type (should show ext4, not 9p)
-df -h /workspaces/cdk-api
+**CloudFront Functions** run on every request with sub-millisecond overhead. They handle the fast checks — is there a valid session cookie? Is the token format correct? Has this session been revoked? They can check revocation state against CloudFront KeyValueStore, which gives you a globally distributed, low-latency lookup table that's eventually consistent in seconds.
 
-# Check kernel (should show WSL2)
-uname -a
-```
+**Lambda@Edge** handles the heavier work — full JWT validation, token exchange during OAuth callbacks, session establishment, HMAC signature verification. These run at regional edge caches, not every PoP, but they only fire on cache misses or specific request patterns like the auth callback.
 
-**Expected output**: `/dev/sd*` device with `ext4` filesystem and `microsoft-standard-WSL2` kernel.
+**WAF** sits in front of the distribution and handles L7 filtering — rate limiting, geo-blocking, bot detection, IP reputation. This is your first line of defence before the request even reaches your CloudFront Function.
 
-### Architecture
+**KVS (KeyValueStore)** gives you real-time session revocation. When you need to kill a session — compromised credentials, user logout, policy change — you write to KVS and within seconds, every edge node worldwide will reject that session. No waiting for token expiry.
 
-Your development environment runs as: **Windows → WSL2 → Docker → Dev Container**
+Together, these layers give you: identity verification, session management, real-time revocation, and L7 threat filtering. All at the edge. All before your origin sees a single request.
 
-- Files are stored natively in WSL2's ext4 filesystem (not Windows NTFS)
-- Docker engine runs in WSL2
-- Dev container runs in Docker with direct access to WSL2 filesystem
-- Result: Native Linux I/O performance for operations like `npm install` and `yarn`
+## Identity Provider Flexibility
 
-### Note on Remote Explorer
+This pattern is identity-provider agnostic. The edge functions validate JWTs — they don't care who issued them.
 
-The devcontainer will appear under **Dev Containers** in VS Code Remote Explorer, not under WSL Targets. This is correct - you're connected to the container, which is hosted by Docker in WSL2.
+I've implemented this with two providers:
 
-## Setup Process
+**Amazon Cognito** works well for B2C applications or when you want a fully managed user directory within AWS. Straightforward OAuth 2.0 / OIDC flows, user pools with MFA, and it integrates natively.
 
-When the devcontainer is created, the `postCreateCommand` runs:
-```bash
-chmod +x .devcontainer/setup.sh .devcontainer/scripts/*.sh && .devcontainer/setup.sh
-```
+**Microsoft Entra ID (Azure AD)** is the enterprise play. If your organisation already uses Microsoft 365, your users already have identities in Entra ID. Federating CloudFront auth against Entra ID means single sign-on for your corporate web apps with no additional user directory to manage. This is a common pattern in enterprises running workloads on AWS but using Microsoft for identity.
 
-This command:
-1. Makes all shell scripts executable (`chmod +x`)
-2. Runs the main setup script (`setup.sh`) only if the chmod succeeds (`&&`)
+The edge functions handle the OAuth dance — authorization code flow, token exchange, session cookie creation — regardless of which provider issued the tokens.
 
-## What Gets Installed
+## Where It Fits in Defence in Depth
 
-### Base Features
-- **TypeScript/Node.js 22**: Main development environment
-- **AWS CLI**: Command line interface for AWS services
-- **Docker-in-Docker**: Ability to run Docker containers within the devcontainer
-- **Python**: Python runtime and tools
+I'm not arguing this should be your *only* enforcement point in every case. Where it sits depends on what you're protecting.
 
-### VS Code Extensions
-- TypeScript language support
-- AWS Toolkit for VS Code
-- Amazon Q for VS Code
-- GitHub Actions support
-- JSON language support
-- Python language support and linting
+For a static single-page application or a content site with authenticated access, edge auth might be all you need. The origin is an S3 bucket. There's no application server to compromise. Enforcing auth at the edge and using Origin Access Control to lock the bucket down is a complete solution.
 
-### Setup Scripts
+For applications with complex business logic, sensitive data, or regulatory requirements, edge auth is your *first* enforcement point. Your API layer still validates tokens, your backend still enforces authorisation, your database still has row-level security. But the edge layer means unauthenticated and revoked sessions never reach any of that infrastructure. It reduces your attack surface and your compute costs — why pay for your origin to reject requests that should never have arrived?
 
-The main `setup.sh` orchestrates the following individual setup scripts:
+The choice is a spectrum, not a binary. In reality, this is likely a mixed model. Your ZTNA solution might still have a role — for legacy apps, thick client access, non-HTTP protocols, the things that don't flow through a CDN. That might be your IT team and a handful of power users. But if 90% of your workforce is accessing web applications through a browser, that's 90% of your ZTNA licensing you could potentially carve off.
 
+That's not a rounding error. That's a material cost reduction.
 
-#### 2. Dependencies Installation (`scripts/install-deps.sh`)
-- Runs `yarn install` to install project dependencies
+## Web Apps — Yes. Legacy — It Depends.
 
-#### 3. AWS Setup (`scripts/aws-setup.sh`)
-- Creates AWS configuration directory
-- Sets up AWS SSO profile configuration
-- Configures default region (ap-southeast-2)
-- **Note**: Contains placeholder values that need to be updated
+This pattern works exceptionally well for modern web applications, which are a huge and growing part of the landscape. SPAs, server-rendered apps, static sites with authenticated APIs — anything that runs in a browser and speaks HTTP.
 
-#### 4. MCP Setup (`scripts/mcp-setup.sh`)
-- Configures Model Context Protocol for Amazon Q
-- Sets up filesystem, git, and AWS MCP servers
-- Creates configuration in `~/.config/amazonq/mcp.json`
+Where it gets harder is legacy applications. Apps that rely on server-side session state, non-standard authentication flows, thick client protocols, or anything that doesn't naturally sit behind a CDN. You can sometimes put a reverse proxy pattern in front of these, but you're fighting the architecture rather than working with it. For those workloads, traditional ZTNA tools or network-level controls may still be the right answer.
 
-## Configuration Files
+But be honest about the ratio. How much of your portfolio is web-based versus truly legacy? For most organisations, it's a significant majority.
 
-- `devcontainer.json`: Main devcontainer configuration
-- `setup.sh`: Main setup orchestrator
-- `scripts/`: Individual setup scripts for different components
+## You Don't Need Another Overlay
 
-## User
+This is the point I really want to make. The major cloud providers and CDN vendors have given you programmable compute at the edge, global key-value stores, managed WAF, and native integration with identity providers. These are production-grade, globally distributed services that handle millions of requests per second.
 
-The container runs as the `node` user for several important reasons:
-- **Security**: Avoids running as root, following the principle of least privilege
-- **Compatibility**: Pre-configured with proper permissions for Node.js development and NPM/Yarn package management
-- **Standards**: Follows Node.js Docker image conventions and integrates well with VS Code devcontainers
-- **Environment**: Provides a proper home directory (`/home/node`) for configuration files and shell access
+You don't need to buy a separate zero trust product to sit in front of your web applications. You need to *configure the infrastructure you already have*.
 
+There's a scaling argument here too. ZTNA overlay products funnel your traffic through resource-constrained nodes that you have to size, manage, and hope will scale when you need them to. CDNs are built to scale. That's their entire reason for existing. CloudFront operates across 600+ points of presence. You're not going to outgrow it.
 
-## Known Issues
+The tools are there. CloudFront Functions, Lambda@Edge, WAF, KVS on AWS. Workers, KV, WAF on Cloudflare. Front Door, Rules Engine, Functions on Azure. The concept is the same — programmable edge compute enforcing identity and policy before traffic reaches your origin.
 
-### MCP Setup
-The Model Context Protocol (MCP) setup is not 100% configured correctly. Some manual configuration may be required after the devcontainer is created.
+## Proof of Concept
 
-### Git LFS
-The repository is configured for Git LFS but `git-lfs` is not installed in the devcontainer. You may see warnings about missing Git LFS. To resolve, either:
-- Install Git LFS: `sudo apt-get update && sudo apt-get install git-lfs`
-- Or remove Git LFS hooks if not needed: `rm .git/hooks/post-commit`
+This repository ([`raindancers-cloudfront`](https://github.com/raindancers/raindancers-cloudfront)) is a CDK construct library published on npm that implements this pattern for AWS. It wires up CloudFront, Lambda@Edge, CloudFront Functions, WAF, KVS, and supports both Cognito and Entra ID authentication flows.
 
-## Logs
+I want to be upfront — this is a proof of concept, not a battle-hardened production library. It needs more work, more testing, and more eyes on it. But it does enough to prove that the concept works end to end. You can stand up a CloudFront distribution with full OAuth 2.0 auth, session management, real-time revocation, and WAF protection using a handful of CDK constructs.
 
-Setup progress is logged to `~/setup.log` for troubleshooting.
+If the idea interests you, take a look, pull it apart, tell me what's broken. That's how it gets better.
 
-## Customization
+## The Challenge
 
-To modify the setup:
-1. Edit the relevant script in the `scripts/` directory
-2. Update AWS configuration in `aws-setup.sh` with your actual values
-3. Modify NPM configuration in `npm-setup.sh` if using different registries
-4. Rebuild the devcontainer to apply changes
+Next time someone puts a ZTNA product evaluation on your desk, ask one question first: what can our CDN already do?
 
-**Adding New Scripts**: You can create additional setup scripts in the `scripts/` directory. They will automatically be made executable by the `postCreateCommand`. Remember to call your new script from `setup.sh` to include it in the setup process.template
+Imagine carving 90% off that licensing cost — and getting better scale in the process. That's worth an afternoon's investigation.

package/package.json

@@ -54,7 +54,7 @@
   },
   "main": "lib/index.js",
   "license": "Apache-2.0",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "jest": {
     "coverageProvider": "v8",
     "testMatch": [