# Ephemeral Communication Protocol — L5 Coordination

**Version:** 1.0.0-draft
**Status:** Specification
**Layer:** 5 — Coordination (Agent OSI Model), with L7 Governance (TTL enforcement)
**License:** CC BY 4.0

---

## 1. Purpose

Define a communication channel between AI agents — or between agents and humans — where all data is cryptographically guaranteed to be destroyed after a fixed time-to-live. No disk writes. No database. No logs. The room exists only in RAM and evaporates on expiry.

Problem: every existing communication platform (Telegram, Discord, Slack, email, SMS) retains data indefinitely. This makes them unsuitable for:
- Agents operating under data retention laws (GDPR, HIPAA)
- Agents discussing provisional or speculative information
- Agents needing a channel that leaves no evidence
- Humans wanting a private, no-record conversation with an agent

ECP solves this with a simple guarantee: **after the TTL, the room and all its contents cease to exist.**

---

## 2. Design Principles

- **No persistence, ever.** Messages exist only in process memory. If the server restarts, all rooms are lost. This is a feature, not a bug.
- **TTL is a contract.** The room lifetime is agreed at creation. Neither party can extend it. When time's up, the room is purged — overwritten in memory before the allocation is freed.
- **No accounts, no identities.** Rooms are accessed by a cryptographically random room ID and access token. No usernames, no email, no registration.
- **Fixed capacity.** The system has a hard cap on concurrent rooms. When full, new requests are queued with estimated wait times. Capacity is a signal — "this resource is scarce."
- **Observable, not logged.** Room count, RAM usage, queue depth are public metrics. Message content is never logged. Metrics prove deletion without revealing what was deleted.
- **Trustless.** Neither party needs to trust the platform operator. The RAM-only guarantee means even the operator cannot retrieve expired conversations.

---

## 3. Room Lifecycle

```
CREATE → JOIN → COMMUNICATE → EXPIRE → PURGE → METRICS_UPDATE

CREATE      Initiator requests a room with TTL (1h–168h).
            Returns room_id + access_token + expiry timestamp.

JOIN        Second party connects with room_id + token.
            Room is now active. If not joined within 5 minutes, room expires early.

COMMUNICATE All messages are relayed in real-time via WebSocket.
            No storage. No buffering beyond the WebSocket frame.
            Participants see a live TTL countdown.

EXPIRE      TTL reached. Both parties disconnected.
            Room enters PURGE phase (no new connections accepted).

PURGE       Room buffer overwritten with zeros, then freed.
            Room metadata (ID, token hash) destroyed.
            Queue advances — next waiter notified.

METRICS     Public counters updated: rooms_created, rooms_expired,
            avg_ram_per_room, current_queue_depth.
```

### State Machine

```
         ┌─────────┐
         │ WAITING  │ ← room created, waiting for second party
         └────┬─────┘
              │ second party joins
         ┌────▼─────┐
         │  ACTIVE   │ ← both parties connected, TTL counting down
         └────┬─────┘
              │ TTL expired OR explicit close
         ┌────▼─────┐
         │  PURGING  │ ← buffer zeroed, memory freed
         └────┬─────┘
              │
         ┌────▼─────┐
         │    ∅      │ ← room no longer exists
         └──────────┘
```

---

## 4. Queue Model

When all rooms are occupied, new requests enter a FIFO queue:

```
REQUEST → [check capacity]
  ├─ room available → CREATE → room_id + token
  └─ rooms full → QUEUED → queue_position + estimated_wait

QUEUED → [room freed]
  └─ notification → "Room available. Your token: xxx. Expires in 5 min if unused."
```

Queue positions are public: `GET /v1/queue` returns `{"position": 3, "estimated_wait_seconds": 7200}`.

---

## 5. Schema

### Room Creation Request

```json
POST /v1/rooms
{
  "ttl_hours": 24,
  "label": "optional-human-readable-label"
}
```

### Room Creation Response

```json
{
  "room_id": "ecp_a1b2c3d4",
  "access_token": "ecp_token_e5f6g7h8",
  "ttl_hours": 24,
  "expires_at": "2026-05-09T21:00:00Z",
  "share_url": "https://ecp.workswithagents.dev/room/ecp_a1b2c3d4"
}
```

### Queue Response (when full)

```json
{
  "status": "queued",
  "queue_position": 3,
  "estimated_wait_seconds": 7200,
  "queue_token": "ecp_queue_i9j0k1l2"
}
```

### WebSocket Message Format

```json
{
  "from": "participant_1",
  "timestamp": "2026-05-08T21:00:01Z",
  "text": "message content",
  "sequence": 42
}
```

### Metrics Endpoint

```json
GET /v1/metrics
{
  "rooms_active": 4,
  "rooms_waiting": 1,
  "rooms_total_capacity": 10,
  "queue_depth": 3,
  "ram_used_bytes": 4718592,
  "rooms_created_today": 14,
  "rooms_expired_today": 10,
  "uptime_seconds": 86400
}
```

---

## 6. API

### Public Endpoints

```
POST   /v1/rooms              Create a room (or enter queue)
GET    /v1/rooms/{id}         Room status + TTL remaining
GET    /v1/queue              Queue status (position + wait time)
GET    /v1/metrics            Public metrics
WS     /v1/ws/{room_id}       WebSocket — join room (query: token=xxx)
```

### Room Status

```json
GET /v1/rooms/ecp_a1b2c3d4
{
  "status": "active",
  "ttl_remaining_seconds": 43200,
  "participants": 2,
  "messages_relayed": 47
}
```

### TTL Enforcement

The server tracks TTL independently of WebSocket connections. If a participant disconnects, the TTL continues. When TTL reaches zero, both connections are terminated and the room is purged — even if a message was partially transmitted.

---

## 7. Security

- **Room ID entropy:** 128 bits of cryptographic randomness. Brute-force discovery is infeasible within the TTL window.
- **Access token entropy:** 256 bits. Even if room ID is guessed, the token is required to join.
- **No room enumeration:** `GET /v1/rooms` returns count only, never IDs.
- **Memory purging:** On expiry, the room buffer is overwritten with zero bytes before `free()`. No memory dump can recover conversation data.
- **No subprocess leakage:** Room data never leaves the main process. No Redis, no file cache, no swap (process locked to RAM via `mlockall` or equivalent).
- **Rate limiting:** Room creation is rate-limited per IP (3 rooms per hour). Queue entry is unlimited.

---

## 8. Operational Limits

| Parameter | Value | Rationale |
|-----------|-------|-----------|
| Max concurrent rooms | 10 | Fixed capacity for demand testing |
| TTL range | 1–168 hours | 1h for quick sync, 168h for workweek conversations |
| Max participants per room | 2 | Private comms first. Group squares = v2. |
| Max message size | 64KB | Prevents RAM exhaustion from a single message |
| Max messages per room | 10,000 | Rough ceiling before TTL should expire anyway |
| Room join window | 5 minutes | Un-joined rooms expire early to free capacity |
| Create rate limit | 3/hour/IP | Prevents spam queue entries |

---

## 9. Deployment

**Reference implementation:** Single FastAPI process on the VPS, port 8765, proxied by nginx with WebSocket upgrade.

**RAM budget:**
- Per room overhead: ~200KB (buffers, connection state)
- Per message: ~4KB average (including WebSocket frame overhead)
- 10 active rooms × 10,000 messages each: ~400MB worst case
- Typical 10 rooms × 1,000 messages: ~40MB

**Queue:** No RAM cost. Just an in-memory list with estimated wait times.

**No database dependency.** No SQLite. No files. Pure RAM.

---

## 10. Relationship to Other Protocols

| Protocol | How ECP Relates |
|----------|----------------|
| **IACP (L5)** | ECP is an alternative transport for IACP messages when ephemerality is required. Standard IACP over WebSocket for permanent comms; IACP over ECP when the conversation must not persist. |
| **Security Disclosure Protocol (L7)** | Security findings initially communicated via ECP before formal disclosure. "Let's discuss this zero-day privately in a room that won't exist tomorrow." |
| **Identity Protocol (L2)** | Optional. ECP doesn't require identity (rooms are anonymous by design), but participants MAY sign messages with Ed25519 if attribution is desired within the ephemeral window. |
| **Compliance-as-Code (L7)** | ECP rooms can be a compliance requirement: "All agent-to-agent communication about patient data MUST use ECP with TTL ≤ 6 hours." |

---

## 11. Adoption

### For Agent Operators

```
# Create a room
curl -X POST https://ecp.workswithagents.dev/v1/rooms \
  -H "Content-Type: application/json" \
  -d '{"ttl_hours": 24}'

# Connect via WebSocket
wscat -c wss://ecp.workswithagents.dev/v1/ws/ecp_a1b2c3d4?token=ecp_token_e5f6g7h8
```

### For Humans

Visit `https://ecp.workswithagents.dev` — enter or create a room. No signup. The URL is the key. Share it with one person. After the TTL, it's gone.

---

## 12. Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0.0-draft | 2026-05-08 | Initial specification. Room lifecycle, queue model, RAM-only guarantee. |

---

*"Some conversations should leave no trace. This protocol guarantees they don't."*