# The Edge Layer MVP: Visibility, Blocking, Deployment, And The App-Coupled WAF

**version** v0.27.58
**date** 18 May 2026
**from** Human (project lead)
**to** Developer (lead), Architect, Security, @Dev
**type** Dev brief

---

## What This Is

The third brief in the security-tools series, and the one that turns the principles and execution model into a concrete first deliverable. The voice memo was explicit: **"the whole point of these memos is to create the first brief for the deployment of this."** This is that brief: the MVP scope.

The MVP focuses on three problems, in priority order: **visibility** (real-time traffic logging and monitoring, fixing the Firehose cost-and-delay problem), **blocking** (the WAF function, doing real security with knowledge of the app it protects), and **deployment** (CLI-driven create, destroy, teardown, fully automated and visualised through the TUI).

It introduces two genuinely novel ideas worth highlighting up front: **the two-way conversation with the edge functions** (you can ping them, query them, ask "what do you know about me?", and configure them through an API), and **the app-coupled WAF** (the WAF knows about the application it protects because the backend communicates with it, removing the complexity that plagues traditional WAFs that operate blind to their applications).

This brief defines the MVP scope, the three problem areas in detail, the two-way conversation mechanism, the coupling principle, the code-discipline requirements, and the specific debugging goals that motivate the whole thing.

## The MVP's Three Problems

The MVP is deliberately scoped to three problems the project lead has right now.

### Problem 1: Visibility

The primary problem. **Real-time visibility into traffic, replacing the CloudWatch + Firehose pipeline that is expensive, delayed, over-complex, and not fully controllable.**

What the MVP delivers:

| Capability | Detail |
|------------|--------|
| **Real-time logs** | Traffic visible as it happens, not minutes later via Firehose |
| **Real-time monitoring** | Live view of what is hitting the site right now |
| **Clean, well-formatted data** | The edge parses and cleans data before it goes downstream; downstream gets good data, not raw mess |
| **Configurable capture** | Map out exactly what we capture and what we do not |
| **Privacy controls** | Option to not log IP addresses in some situations (configurable); or to log them specifically when a threat is suspected |
| **Cost control** | Logging to our own storage in our own format; far cheaper than Firehose at volume |

The voice memo named the Firehose problems precisely: cost (overkill for what we need), latency (not real real-time; delays we do not control), and complexity (more moving parts than the job requires). The MVP replaces it with something we control end to end.

The privacy angle is worth noting: **not logging IP addresses can be a feature, not a gap.** In some situations, not capturing an IP is the privacy-respecting choice; in others (suspected threat), capturing it is the security choice. The edge layer makes this a configuration decision rather than an all-or-nothing platform behaviour.

### Problem 2: Blocking (The App-Coupled WAF)

The second problem: **start removing and reacting to bad traffic. A WAF, but a modern one built with full access to our stack, including the backend.**

The voice memo named the core insight that distinguishes this from every traditional WAF: **most WAFs operate blind to the application they protect.** They block based on generic signatures and patterns because they have no knowledge of what the protected app actually does. This blindness is the source of most WAF complexity and most WAF false positives.

Our WAF inverts this. **There is massive coupling between the security layer and the thing it protects.** The backend can communicate with the WAF; the WAF knows what the app expects; the WAF can make precise decisions because it understands the application. The voice memo: **"what would it take, and how would we build it, so that we can add a lot of intelligence to the WAF that comes from the application that the WAF is actually protecting?"**

This coupling is the key principle, and it removes complexity rather than adding it:

| Traditional WAF | App-Coupled WAF |
|-----------------|------------------|
| Blind to the app; uses generic rules | Knows the app; uses precise rules |
| High false-positive rate | Low false-positive rate (knows what valid looks like) |
| Complex rule tuning to avoid breaking the app | Rules derived from the app's actual contract |
| Cannot tell a real request from a crafted one | Can, because it knows the legitimate request profile |
| Security team maintains rules separately | App and WAF rules move together (the symmetry principle) |

The coupling connects directly to the no-invalid-request principle from the execution-model brief. The WAF knows what valid traffic looks like (from the app), so it can drop everything else. **The intelligence comes from the application, not from generic threat databases.**

### Problem 3: Deployment

The third problem: **all the CLI commands, all the deployment automation, create, destroy, teardown, fully automated and visualised.**

The voice memo emphasised that deployment is a core principle, not an afterthought, and that **the visualisation of the deployment is why the TUI matters.** The MVP must make deploying the edge layer to a CloudFront distribution (and tearing it down) a clean, fast, observable operation.

What the MVP delivers:

| Capability | Detail |
|------------|--------|
| **Create** | Deploy the edge layer to a CloudFront distribution via CLI |
| **Destroy / teardown** | Cleanly remove it; no orphaned resources |
| **Automation** | The full lifecycle scripted; no manual AWS console steps |
| **Visualisation** | The TUI shows deployment state, what is deployed where, health |
| **Genericity** | Easy to deploy to many distributions; "deploy this left, right, and centre" |

The voice memo noted we already have many CloudFront distributions and Lambda functions to protect, and that the existing SG/Compute plumbing (which already deploys CloudFront distributions and a simple function) is the foundation. The MVP extends this to deploy the security/logging/routing functions.

## The Two-Way Conversation With Edge Functions

The most novel idea in the voice memo, and worth treating as a first-class MVP feature: **the ability to talk to the edge functions directly.** Not just deploy them and watch logs flow, but actually converse with them, query them, and configure them through an API.

The capabilities:

| Capability | What It Does |
|------------|--------------|
| **Ping** | Confirm an edge function is alive and responding |
| **Query state** | Ask the function what it knows, what it is doing, what it has seen |
| **Admin interface** | Configure the function; adjust rules; change settings (API-key protected) |
| **Debug introspection** | "What the hell is going on" visibility into a specific function's behaviour |
| **Configuration** | Update the function's behaviour through the API rather than redeploying |

The voice memo named two reasons this matters:

**First, debugging.** When something is wrong at the edge, being able to ask a function directly "what are you seeing, what are you doing" is far better than inferring from logs. The edge functions can write to whatever we want; making them queryable turns them into debuggable components.

**Second, and more subtly: in an isolated environment, the edge functions' API may be the only thing you can talk to.** The voice memo: **"this should be deployed on every isolated environment, so when I deploy this to an isolated environment, I need a way to make sure it works, and it could be that the only thing we can talk to at that moment is these APIs."** The edge function's API becomes the diagnostic entry point for the whole isolated deployment.

This must be **API-key protected from the start.** An admin interface to the edge functions is a sensitive surface; it ships with authentication, not as a follow-on.

### The "What Do You Know About Me?" Feature

A specific and genuinely interesting idea within the two-way conversation: **let legitimate users ask what the system knows about them.**

For legit users in legit situations, the edge layer could expose: what we have logged about this user, what we are capturing, what intelligence we have derived. This is a privacy-respecting, transparency-forward feature that turns the logging system into something users can interrogate about themselves.

This connects to broader data-subject-access patterns (the kind of thing privacy regulations encourage) but implemented natively: because the edge layer captures the traffic data, it can answer "what do you know about me?" directly. The voice memo flagged it could even use IP-data and threat-intelligence analysis to give users a meaningful answer.

This is a v1.5 feature rather than strict MVP, but worth designing toward because the architecture makes it nearly free: the data is already captured; exposing a scoped, authenticated view to the legitimate subject is a small addition with a strong privacy story.

## The Layer 3 Async / Agentic Path

The voice memo wants to explore the async path (Layer 3 from the execution-model brief), where the capable Lambda functions trigger analysis and agentic flows. Specifically: **using Nova and other Bedrock models to do analysis and trigger activities, asynchronously, executing within seconds.**

This is where the edge layer becomes genuinely intelligent:

- A Layer 2 function notices something suspicious and triggers a Layer 3 async analysis
- The Layer 3 function uses Nova (cheap, fast) to analyse the pattern
- The analysis result feeds back: update Layer 1's banned list, adjust Layer 2's rules, alert an operator
- All within seconds, off the hot path

The voice memo connected this to the agentic-flows direction: **"we can even trigger agentic flows from here, that third level of functions which are asynchronous, not inline, but execute within seconds."** This is the "slow analysis, fast enforcement" pattern from the execution-model brief, made concrete with Bedrock models.

For the MVP this is exploratory rather than core, but the architecture should leave room for it: Layer 2 functions should be able to trigger Layer 3 async work, and Layer 3 should be able to feed results back to Layers 1 and 2.

## The Code Discipline Requirements

The voice memo was emphatic about code quality and size, and it shapes the implementation:

| Requirement | Detail |
|-------------|--------|
| **As small as possible** | Minimal footprint; the edge functions especially must be lean |
| **Ideally no runtime dependencies** | Especially Layer 1; dependencies are weight and risk |
| **High quality, well-structured** | Small does not mean sloppy; this is security code |
| **Language pragmatic** | Python preferred for readability, but no hard restriction |
| **Go / Rust acceptable for performance** | Where performance genuinely matters, the lower-level languages are fine |
| **Optimise at the right altitude** | The key discipline (see below) |

The "optimise at the right altitude" point is important and the voice memo made it sharply: **there is no point shaving 5-50ms off a Lambda's execution when that Lambda then opens a file from S3 or makes a network call that takes 50ms.** Optimise where the time actually goes. Layer 1 (sub-millisecond, no I/O) is where micro-optimisation matters; Layer 2 (does I/O) is dominated by the I/O, so language-level micro-optimisation there is mostly wasted effort.

The practical implication: **Layer 1 should be ruthlessly lean** (it runs on every request, sub-millisecond, no dependencies). **Layer 2 can be more relaxed about language-level performance** because its latency is dominated by the network and file operations it performs. Measure where the time goes before optimising.

The voice memo also flagged **lift-and-shift from existing code**: much of the logic and many of the examples and workflows exist in our other work and can be adapted. The edge layer is not built from scratch; it assembles and slims down existing patterns.

## The Specific Debugging Goals

The voice memo named concrete debugging goals that motivate the visibility work. Worth capturing because they are the acceptance test for whether the MVP delivers:

| Goal | Detail |
|------|--------|
| **Understand clone traffic patterns** | Clones have caused bugs via too many requests; we need to see this clearly |
| **Understand the too-many-requests bugs** | The runaway-request class of bug; catch it through traffic visibility |
| **Understand performance implications** | What loads fast, what loads slow, why |
| **Debug the mobile load issue** | The site took longer than expected to load on a phone yesterday; understand why |
| **Distinguish version-to-version behaviour** | See how traffic and performance change between deployments |

These are the real, current problems. If the MVP gives the project lead clear visibility into clone traffic patterns, the too-many-requests bugs, and the mobile load performance, it has delivered its primary value. **The MVP is judged against these concrete debugging goals, not against abstract WAF feature checklists.**

## The "Don't Play Ball With Attackers" Stance

A framing principle worth capturing: **our job is to make the attacker's job as hard as possible; we do not have to play fair.**

The voice memo: **"we don't have to play ball with the attackers; our job is to make the attacker's job as hard as possible."** This licenses aggressive, asymmetric responses:

- Drop bad traffic silently (give attackers no feedback)
- Send bad traffic on wild goose chases (waste their time)
- Vary responses to make probing unreliable
- Capture extra data on suspected threats while minimising data on legitimate users
- Use the async layer to analyse and ban without the attacker knowing they have been detected

This is the inverse of the privacy-respecting stance toward legitimate users. **Legitimate users get transparency ("what do you know about me?") and minimal data capture; suspected attackers get opacity, friction, and asymmetric treatment.** The edge layer can tell the difference because it knows what good looks like (the coupling principle).

## How The MVP Composes With The Series

This MVP brief sits between the architecture briefs and implementation:

| Brief | Relationship |
|-------|--------------|
| Principles brief | The why and the principles this MVP implements |
| Execution-model brief | The layered model this MVP builds the first version of |
| **This MVP brief** | **The concrete first deliverable** |
| (Future) Layer 2 logic brief | What the capable functions do in detail |
| (Future) LLM-decision brief | The Layer 3 agentic analysis in detail |

The MVP delivers Layer 1 (lean, fast, logging and blocking), the beginnings of Layer 2 (request validation, the app coupling), the deployment automation, the two-way conversation API, and the TUI for visibility. Layer 3 async/agentic is exploratory in the MVP and detailed in a later brief.

## What This Asks For

Concrete next steps:

1. **Build the Layer 1 logging function** that captures real-time traffic, cleanly formatted, with configurable privacy (IP logging on/off).
2. **Build real-time log delivery** to our own storage, replacing Firehose.
3. **Build the edge TUI** for real-time traffic visibility (the primary deliverable).
4. **Build the Layer 1 blocking function** (banned IPs/regions, malformed-request rejection).
5. **Build the two-way conversation API** (ping, query, admin), API-key protected from the start.
6. **Establish the app-coupling mechanism** (how the backend tells the WAF what valid traffic looks like).
7. **Build the deployment automation** (create, destroy, teardown via CLI; visualised in the TUI).
8. **Extend the existing SG/Compute CloudFront plumbing** to deploy these functions.
9. **Measure performance** at each layer; populate the TUI with hot data.
10. **Validate against the debugging goals** (clone traffic, too-many-requests, mobile load).
11. **Design (not necessarily build) the "what do you know about me?" feature** for legit users.
12. **Leave room for the Layer 3 async/agentic path** without building it fully in the MVP.

Estimated effort: 2-3 weeks for the MVP with Layer 1, real-time logging, the TUI, deployment automation, and the two-way API. The app-coupling and Layer 3 paths are follow-on.

## What This Does Not Try To Be

Deliberate scope limits:

- **Not the full WAF feature set.** The MVP does logging, basic blocking, and the coupling foundation; the full security rule engine is later.
- **Not Layer 3 agentic in v1.** The async/LLM path is explored, not fully built, in the MVP.
- **Not SSL termination.** Still later, per the execution-model brief.
- **Not multi-CDN.** CloudFront first.
- **Not the "what do you know about me?" feature fully built.** Designed toward; built later.
- **Not a commercial product.** Internal infrastructure first.

## Honest Risks

Three risks:

**Risk 1: The two-way conversation API is a new attack surface.** An admin interface to edge functions, if compromised, is serious. Mitigation: API-key protected from the start (non-negotiable); minimal surface; audit every call; consider mTLS or stronger auth for the admin functions.

**Risk 2: Real-time logging at volume could itself become a cost or performance problem.** The thing we are replacing Firehose to avoid. Mitigation: measure the logging overhead; keep Layer 1 logging lean; batch and compress; ensure the cure is cheaper than the disease.

**Risk 3: The app-coupling mechanism could create tight, fragile coupling.** If the WAF breaks every time the app changes, that is worse than a blind WAF. Mitigation: the coupling is via a clean contract (the known-good profile / OpenAPI spec), automated as part of deployment (the symmetry principle); observe-mode before enforce-mode.

## Open Questions

| Question | Notes |
|----------|-------|
| Real-time log storage destination? | Our own storage; S3 + vault likely; format TBD |
| Two-way API auth: API key only, or stronger? | API key minimum; mTLS for admin functions worth considering |
| App-coupling contract format? | Probably OpenAPI / known-good profile; per the execution-model brief |
| Language for Layer 1? | JavaScript (CloudFront Functions constraint); lean |
| Language for Layer 2? | Python preferred; Go/Rust if perf demands; measure first |
| "What do you know about me?" auth model? | Strong; only the authenticated subject sees their own data |
| How much Layer 3 to build in MVP? | Leave the hook; do not build the full agentic path yet |
| Logging privacy default: log IPs or not? | Configurable; default probably minimal; threat-triggered capture |

## Relationship To Previous Briefs

| Date | Document | Relationship |
|---|---|---|
| 18 May | `v0.27.58__arch-brief__edge-security-and-logging-layer-principles.md` | The principles this MVP implements |
| 18 May | `v0.27.58__arch-brief__edge-layer-execution-model-layered-responders.md` | The execution model this MVP builds the first version of |
| 17 May | `v0.27.55__dev-brief__sg-edge-tui-first-five-screens.md` | The TUI screens (live event stream) this MVP uses for visibility |
| 17 May | `v0.27.55__arch-brief__tui-api-structured-surface-for-text-uis.md` | The two-way conversation API follows the TUI API pattern |
| 17 May | `v0.27.55__arch-brief__tui-api-extensions-iam-memfs-orientation.md` | The IAM and orientation patterns apply to the edge admin API |
| 17 May | `v0.27.55__article__de-commoditising-the-commodity.md` | The MVP is the shield over Firehose/WAF attrition |
| 16 May | `v0.27.45__dev-brief__on-demand-vault-provisioning-workflows.md` | The CloudFront plumbing this extends |
| 16 May | `v0.27.45__dev-brief__nova-and-agentcore-poc-fastapi.md` | Nova for the Layer 3 async analysis |
| 16 May | `v0.27.45__arch-brief__vault-discovery-and-public-keys.md` | PKI for the two-way API auth |
| 14 May | `v0.27.41__strategy-brief__preauth-micropayments-monetisation-model.md` | Edge cost tracking |

---

## Acceptance Criteria

| # | Criterion | Verification |
|---|-----------|-------------|
| 1 | Real-time traffic logging works, replacing Firehose | Logs visible in real time; cost lower |
| 2 | Configurable privacy (IP logging on/off) works | Configuration honoured |
| 3 | The edge TUI shows real-time traffic | Hot data visible |
| 4 | Layer 1 blocking (IPs, regions, malformed) works | Bad traffic dropped at the edge |
| 5 | The two-way conversation API works (ping, query, admin) | API-key protected; responds |
| 6 | The app-coupling mechanism passes valid-traffic knowledge to the WAF | Backend informs the edge |
| 7 | Deployment automation (create, destroy, teardown) works via CLI | Clean lifecycle; no orphans |
| 8 | Deployment is visualised in the TUI | State visible |
| 9 | Performance is measured at each layer | Hot data populates the TUI |
| 10 | The debugging goals are met (clone traffic, too-many-requests, mobile load) | Real problems become visible |
| 11 | Layer 1 code is lean (minimal/no dependencies) | Footprint verified |
| 12 | The Layer 3 async hook exists (even if not fully built) | Architecture leaves room |

---

This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).