# Session Brief: core/go-p2p

**Repo**: `forge.lthn.ai/core/go-p2p` (clone at `/tmp/core-go-p2p`)
**Module**: `forge.lthn.ai/core/go-p2p`
**Status**: 16 Go files, ~2,500 LOC, node tests PASS (42% coverage), ueps has NO TESTS
**Wiki**: https://forge.lthn.ai/core/go-p2p/wiki (6 pages)

## What This Is

P2P networking layer for the Lethean network. Three packages:

### node/ — P2P Mesh (14 files)
- **Identity**: Ed25519 keypair generation, PEM serialisation, challenge-response auth
- **Transport**: Encrypted WebSocket connections via gorilla/websocket + Borg (encrypted blob storage)
- **Peers**: Registry with scoring, persistence, auth modes (open/allowlist), name validation
- **Messages**: Typed protocol messages (handshake, ping, stats, miner control, deploy, logs)
- **Protocol**: Response handler with validation and typed parsing
- **Worker**: Command handler (ping, stats, miner start/stop, deploy profiles, get logs)
- **Dispatcher**: UEPS packet routing skeleton with threat circuit breaker
- **Controller**: Remote node operations (connect, command, disconnect)
- **Bundle**: Service factory for Core framework DI registration

### ueps/ — Wire Protocol (2 files, NO TESTS)
- **PacketBuilder**: Constructs signed UEPS frames with TLV encoding
- **ReadAndVerify**: Parses and verifies HMAC-SHA256 integrity
- TLV tags: 0x01-0x05 (header fields), 0x06 (HMAC), 0xFF (payload marker)
- Header: Version, CurrentLayer, TargetLayer, IntentID, ThreatScore

### logging/ — Structured Logger (1 file)
- Simple levelled logger (INFO/WARN/ERROR/DEBUG) with key-value pairs

## Current State

| Area | Status |
|------|--------|
| node/ tests | PASS — 42% statement coverage |
| ueps/ tests | NONE — zero test files |
| logging/ tests | NONE |
| go vet | Clean |
| TODOs/FIXMEs | None found |
| Identity (Ed25519) | Well tested — keypair, challenge-response, deterministic sigs |
| PeerRegistry | Well tested — add/remove, scoring, persistence, auth modes, name validation |
| Messages | Well tested — all 15 message types, serialisation, error codes |
| Worker | Well tested — ping, stats, miner, deploy, logs handlers |
| Transport | NOT tested — WebSocket + Borg encryption |
| Controller | NOT tested — remote node operations |
| Dispatcher | NOT tested — UEPS routing skeleton |

## Dependencies

- `github.com/Snider/Borg` v0.2.0 (encrypted blob storage)
- `github.com/Snider/Enchantrix` v0.0.2 (secure environment)
- `github.com/Snider/Poindexter` (secure pointer)
- `github.com/gorilla/websocket` v1.5.3
- `github.com/google/uuid` v1.6.0
- `github.com/ProtonMail/go-crypto` v1.3.0
- `github.com/adrg/xdg` v0.5.3
- `github.com/stretchr/testify` v1.11.1
- `golang.org/x/crypto` v0.45.0

## Priority Work

### High (coverage gaps)
1. **UEPS tests** — Zero tests for the wire protocol. This is the consent-gated TLV protocol from RFC-021. Need: builder round-trip, HMAC verification, malformed packet rejection, boundary conditions (max ThreatScore, empty payload, oversized payload).
2. **Transport tests** — WebSocket connection, Borg encryption handshake, reconnection logic.
3. **Controller tests** — Connect/command/disconnect flow.
4. **Dispatcher tests** — UEPS routing, threat circuit breaker (ThreatScore > 50000 drops).

### Medium (hardening)
5. **Increase node/ coverage** from 42% to 70%+ — focus on transport.go, controller.go, dispatcher.go
6. **Benchmarks** — Peer scoring, UEPS marshal/unmarshal, identity key generation
7. **Integration test** — Full node-to-node handshake over localhost WebSocket

### Low (completeness)
8. **Logging tests** — Simple but should have coverage
9. **Peer discovery** — Currently manual. Add mDNS or DHT discovery
10. **Connection pooling** — Transport creates fresh connections; add pool for controller

## File Map

```
/tmp/core-go-p2p/
├── node/
│   ├── bundle.go          + bundle_test.go       — Core DI factory
│   ├── identity.go        + identity_test.go     — Ed25519 keypair, PEM, challenge-response
│   ├── message.go         + message_test.go      — Protocol message types
│   ├── peer.go            + peer_test.go         — Registry, scoring, auth
│   ├── protocol.go        + protocol_test.go     — Response validation, typed parsing
│   ├── worker.go          + worker_test.go       — Command handlers
│   ├── transport.go       (NO TEST)              — WebSocket + Borg encryption
│   ├── controller.go      (NO TEST)              — Remote node operations
│   ├── dispatcher.go      (NO TEST)              — UEPS routing skeleton
│   └── logging.go                                — Package-level logger setup
├── ueps/
│   ├── ueps.go            (NO TEST)              — PacketBuilder, ReadAndVerify, TLV
│   └── types.go           (NO TEST)              — UEPSHeader, ParsedPacket, intent IDs
├── logging/
│   └── logger.go          (NO TEST)              — Levelled structured logger
├── go.mod
└── go.sum
```

## Key Interfaces

```go
// node/message.go — 15 message types
const (
    MsgHandshake    MsgHandshakeAck   MsgPing        MsgPong
    MsgDisconnect   MsgGetStats       MsgStats       MsgStartMiner
    MsgStopMiner    MsgMinerAck       MsgDeploy      MsgDeployAck
    MsgGetLogs      MsgLogs           MsgError
)

// ueps/types.go — UEPS header
type UEPSHeader struct {
    Version      uint8   // 0x09
    CurrentLayer uint8
    TargetLayer  uint8
    IntentID     uint8   // 0x01=Handshake, 0x20=Compute, 0x30=Rehab, 0xFF=Extended
    ThreatScore  uint16
}
```

## Conventions

- UK English
- Tests: testify assert/require
- Licence: EUPL-1.2
- Lethean codenames: Borg (Secure/Blob), Poindexter (Secure/Pointer), Enchantrix (Secure/Environment)