# DAMM System Spec

## Purpose

This is the implementation-facing spec for the DAMM MVP.

It should answer:

- what the product is today
- which interfaces are load-bearing
- what invariants the code should preserve
- what “working” means in terms of observable behavior

## Scope

In scope:

- control-plane API
- client CLI
- browser-side client companion
- gateway config rendering
- signed catalog flow
- access-tier policy
- usage metering
- operator report generation
- provider planning and smoke tooling
- site generation for public and operator-facing surfaces

Out of scope for the current repo:

- native GUI VPN apps
- full commercial billing
- live multi-tenant account system
- production-grade gateway config push channel
- browser-resident VPN transport

## Product Contract

DAMM is a WireGuard-based VPN system with:

- client-side device key generation
- control-plane enrollment and policy
- gateway admission by registration and heartbeat
- signed endpoint catalogs for failover
- operator-visible reports and evidence artifacts

## Required Invariants

These invariants should remain true unless explicitly revised.

### Key Invariants

- device private keys never need to reach the control plane
- gateway private keys never need to reach the control plane
- client config rendering can be done entirely from local private key plus server-issued peer material

### Enrollment Invariants

- no enrollment succeeds without a valid enrollment token
- no enrollment succeeds without at least one healthy registered gateway
- no enrollment succeeds if requested policy violates the access tier
- each active device receives exactly one assigned tunnel IP in the state model

### Catalog Invariants

- catalogs are signed
- clients reject stale catalogs
- catalogs only include healthy registered gateways and active front doors

### Lifecycle Invariants

- revoked devices cannot rotate keys
- suspended devices remain visible in reports
- gateway heartbeat before registration is rejected

## Component Specs

## 1. Client CLI

### Commands

- `init`
- `enroll`
- `failover`
- `bundle`
- `diagnose`

### `init`

Inputs:

- device name
- output path

Behavior:

- generate a WireGuard keypair locally
- write a device file containing private key, public key, name, and creation timestamp

### `enroll`

Inputs:

- device file
- control-plane URL
- enrollment token
- optional region
- optional exit country
- config output path

Behavior:

- load device state
- send only the device public key and policy hints
- receive gateway, egress, peer, and catalog data
- write the local WireGuard config
- persist device state

Outputs:

- updated device file
- rendered config file

### `failover`

Inputs:

- device file
- control-plane base URL
- config output path

Behavior:

- fetch catalog
- verify signature and freshness
- choose the next front door
- rewrite the config
- persist failover metadata

### `bundle`

Inputs:

- device file
- config file
- bundle output path

Behavior:

- write profile bundle
- emit OS-specific install notes
- emit preset metadata
- emit DAMM companion URL
- emit QR artifact if tooling exists locally

### `diagnose`

Inputs:

- device file
- config file
- output path

Behavior:

- emit local support artifact
- include current endpoint and profile metadata
- avoid leaking more than the current device profile already contains

## 2. Browser-Side DAMM Client

### Purpose

The DAMM client page is a fully client-side companion.

It exists for:

- profile loading
- install guidance
- profile export
- support and diagnostics handoff

It does not exist to run the tunnel itself.

### Required behavior

- load a local `.conf` file
- parse key metadata such as endpoint, address, and DNS
- preserve the last imported profile in browser storage
- provide device-target install tabs for iPhone, macOS, Android, Linux, and browser companion usage
- remain functional as a standalone saved page

## 3. Control Plane API

### Public / bootstrap endpoints

- `GET /healthz`
- `POST /v1/devices/enroll`
- `GET /v1/catalog`

### Gateway-authenticated endpoints

- `POST /v1/gateways/:gatewayId/register`
- `POST /v1/gateways/:gatewayId/heartbeat`
- `POST /v1/gateways/:gatewayId/devices/:deviceId/meter`

### Admin-authenticated endpoints

- `POST /v1/admin/login`
- `GET /v1/admin/audit`
- `GET /v1/report`
- `GET /v1/state`
- `POST /v1/devices/:deviceId/rotate-key`
- `POST /v1/devices/:deviceId/revoke`

### Request-shape expectations

- JSON bodies only
- bounded body size
- meaningful failure codes for policy and capacity errors

## 4. Gateway Renderer

### Purpose

Render gateway-facing WireGuard config from current state plus gateway private key supplied at render time.

### Required behavior

- read state through the store abstraction
- include current active peers for the target gateway
- never require the control plane to persist the gateway private key

## 5. Operator Report

### Purpose

Produce a concise operator-facing view of:

- gateway health
- egress health
- recent activity
- device usage
- access-tier state
- placement recommendations
- profiling artifacts when available

### Minimum fields

- healthy / stale gateway counts
- recovery endpoint counts
- per-gateway load and headroom
- per-egress load and headroom
- recent audit events
- top devices by visible usage state
- recommendation actions

## State Model

### Gateway record

Required fields:

- id
- name
- region
- provider
- public key
- front doors
- registration state
- heartbeat timestamps
- load metrics

### Device record

Required fields:

- id
- name
- public key
- assigned IP
- gateway attachment
- egress attachment
- access tier
- usage
- lifecycle state

### Access-tier record

Required fields:

- id
- name
- allowed regions
- allowed exit countries
- concurrent session limit
- monthly byte limit
- lifecycle status

## Validation Contract

The following are considered required validation surfaces for the current repo:

- unit and integration tests
- local tracer bullet
- control-plane failure drill
- host WireGuard smoke
- host workload validation
- site build validation
- benchmark and profiling artifacts

## Current Success Criteria

The repo should be considered healthy when all of the following hold:

- `npm test` passes
- `npm run tracer` completes
- `bash scripts/drill-control-plane.sh` completes
- `node scripts/build-site.js` completes
- the operator report page renders from current artifacts
- the DAMM client page renders from current artifacts

When live hosts are available, an additional stronger criterion applies:

- `bash scripts/host-wireguard-workload.sh ...` completes with bidirectional transfer and hash verification

## Known Current Limitations

- JSON remains the validated default backend
- gateway metering is still reported rather than directly enforced in the packet plane
- workload validation is point-to-point rather than yet full gateway-managed end-user routing
- browser-side DAMM client is a companion only