# DAMM Client Boundaries

## Goal

Draw the product boundary cleanly enough that the implementation stays honest on every platform.

## The Boundary

DAMM should be split into three client-facing layers:

1. Native tunnel layer
2. Client-side companion layer
3. Operator and control-plane layer

These layers should not be blurred together.

## 1. Native Tunnel Layer

This is where the actual VPN tunnel runs.

Current correct targets:

- WireGuard for iPhone
- WireGuard for macOS
- WireGuard for Android
- `wg-quick` or NetworkManager on Linux

What belongs here:

- actual packet encryption and transport
- OS-level routing
- network extension / VPN entitlement ownership
- always-on and per-app VPN behavior where the OS supports it

What does not belong here:

- control-plane policy logic
- complex onboarding logic
- diagnostics presentation
- product copy

Reason:

This layer is the most privilege-sensitive part of the product. Keep it boring.

## 2. Client-Side Companion Layer

This is the DAMM browser surface.

Correct shape:

- installable PWA
- works fully client-side
- safe to save to iPhone home screen
- can load, inspect, store, and export DAMM profiles locally

What belongs here:

- local bundle import
- profile inspection
- QR or file-based handoff support
- platform-specific install guidance
- diagnostics capture and export
- reissue / rotate / failover visibility

What does not belong here:

- raw VPN tunneling
- privileged OS route control
- packet interception
- pretending the browser itself is the VPN client

Reason:

iOS browsers do not expose the network privileges required for a real WireGuard tunnel. A browser-resident “VPN client” would either be fake or fragile.

## 3. Browser Extension Layer

This should be treated as a thin companion, not as the VPN implementation.

Correct responsibilities:

- open the DAMM companion quickly
- show current profile metadata
- surface diagnostics state
- hand off files to the native client
- expose shortcuts to operator and account pages

Incorrect responsibilities:

- implement a VPN transport
- own routing
- claim stronger security than the native tunnel layer

Reason:

Extensions are good launchers and surfaces. They are poor substitutes for privileged networking components.

## OS-Level Presets

DAMM should ship presets that describe the intended install and control path per platform.

Minimum preset set:

- `ios-wireguard-import`
- `macos-wireguard-import`
- `android-wireguard-import`
- `linux-wg-quick`
- `desktop-browser-companion`

Each preset should encode:

- target client
- import method
- expected config filename
- support notes
- whether the companion PWA is recommended

## Fancy Routing And Load Balancing

This belongs in the control plane and gateways, not in the PWA.

Correct placement:

- signed catalog selection
- front-door ranking
- gateway health evaluation
- egress pool selection
- placement recommendations
- future multi-gateway balancing logic

The PWA may display routing state, but it must not become the routing authority.

## What This Means For Implementation

Immediate implementation consequences:

1. Keep WireGuard configs as the canonical device artifact.
2. Improve DAMM bundles so they map directly to native import flows.
3. Provide an installable client-side PWA as the human-facing companion.
4. Treat the browser extension as a thin launcher and diagnostics surface.
5. Keep failover, metering, and routing policy in the control plane and native client path.

## Product Honesty Rule

If a surface cannot actually carry the tunnel, it must not imply that it does.

That rule should shape:

- product copy
- landing-page CTAs
- install instructions
- extension scope
- PWA scope