Add WireGuard VPN with random /31 subnet isolation (v0.40.0)

- Add embedded WireGuard VPN server using wireguard-go + netstack
- Implement deterministic /31 subnet allocation from seed + sequence
- Use Badger's built-in Sequence for atomic counter allocation
- Add NIP-46 bunker server for remote signing over VPN
- Add revoked key tracking and access audit logging for users
- Add Bunker tab to web UI with WireGuard/bunker QR codes
- Support key regeneration with old keypair archiving

New environment variables:
- ORLY_WG_ENABLED: Enable WireGuard VPN server
- ORLY_WG_PORT: UDP port for WireGuard (default 51820)
- ORLY_WG_ENDPOINT: Public endpoint for WireGuard
- ORLY_WG_NETWORK: Base network for subnet pool (default 10.0.0.0/8)
- ORLY_BUNKER_ENABLED: Enable NIP-46 bunker
- ORLY_BUNKER_PORT: WebSocket port for bunker (default 3335)

Files added:
- pkg/wireguard/: WireGuard server, keygen, subnet pool, errors
- pkg/bunker/: NIP-46 bunker server and session handling
- pkg/database/wireguard.go: Peer storage with audit logging
- app/handle-wireguard.go: API endpoints for config/regenerate/audit
- app/wireguard-helpers.go: Key derivation helpers
- app/web/src/BunkerView.svelte: Bunker UI with QR codes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

pkg/bunker/server.go

@@ -0,0 +1,182 @@
+// Package bunker provides a NIP-46 remote signing service that listens
+// only on the WireGuard VPN network for secure access.
+package bunker
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net"
+	"net/http"
+	"sync"
+	"time"
+
+	"github.com/gorilla/websocket"
+	"golang.zx2c4.com/wireguard/tun/netstack"
+	"lol.mleku.dev/chk"
+	"lol.mleku.dev/log"
+
+	"git.mleku.dev/mleku/nostr/interfaces/signer"
+)
+
+var upgrader = websocket.Upgrader{
+	ReadBufferSize:  4096,
+	WriteBufferSize: 4096,
+	CheckOrigin:     func(r *http.Request) bool { return true },
+}
+
+// Server is the NIP-46 bunker server.
+type Server struct {
+	relaySigner signer.I      // Relay's signer for signing events
+	relayPubkey []byte        // Relay's public key
+	netstack    *netstack.Net // WireGuard netstack for listening
+	listenAddr  string        // e.g., "10.73.0.1:3335"
+
+	sessions   map[string]*Session // Connection ID -> Session
+	sessionsMu sync.RWMutex
+
+	server *http.Server
+	ctx    context.Context
+	cancel context.CancelFunc
+	wg     sync.WaitGroup
+}
+
+// Config holds bunker server configuration.
+type Config struct {
+	RelaySigner signer.I
+	RelayPubkey []byte
+	Netstack    *netstack.Net
+	ListenAddr  string // IP:port on WireGuard network
+}
+
+// New creates a new bunker server.
+func New(cfg *Config) *Server {
+	ctx, cancel := context.WithCancel(context.Background())
+
+	return &Server{
+		relaySigner: cfg.RelaySigner,
+		relayPubkey: cfg.RelayPubkey,
+		netstack:    cfg.Netstack,
+		listenAddr:  cfg.ListenAddr,
+		sessions:    make(map[string]*Session),
+		ctx:         ctx,
+		cancel:      cancel,
+	}
+}
+
+// Start begins listening for bunker connections on the WireGuard network.
+func (s *Server) Start() error {
+	// Parse listen address
+	host, port, err := net.SplitHostPort(s.listenAddr)
+	if err != nil {
+		return fmt.Errorf("invalid listen address: %w", err)
+	}
+
+	ip := net.ParseIP(host)
+	if ip == nil {
+		return fmt.Errorf("invalid IP address: %s", host)
+	}
+
+	portNum := 0
+	if _, err := fmt.Sscanf(port, "%d", &portNum); err != nil {
+		return fmt.Errorf("invalid port: %s", port)
+	}
+
+	// Create TCP listener on netstack (WireGuard network only)
+	listener, err := s.netstack.ListenTCP(&net.TCPAddr{
+		IP:   ip,
+		Port: portNum,
+	})
+	if err != nil {
+		return fmt.Errorf("failed to listen on netstack: %w", err)
+	}
+
+	// Create HTTP server with WebSocket handler
+	mux := http.NewServeMux()
+	mux.HandleFunc("/", s.handleWebSocket)
+
+	s.server = &http.Server{
+		Handler:      mux,
+		ReadTimeout:  30 * time.Second,
+		WriteTimeout: 30 * time.Second,
+		IdleTimeout:  120 * time.Second,
+	}
+
+	s.wg.Add(1)
+	go func() {
+		defer s.wg.Done()
+		if err := s.server.Serve(listener); err != nil && err != http.ErrServerClosed {
+			log.E.F("bunker server error: %v", err)
+		}
+	}()
+
+	log.I.F("NIP-46 bunker server started on %s (WireGuard only)", s.listenAddr)
+	return nil
+}
+
+// Stop shuts down the bunker server.
+func (s *Server) Stop() error {
+	s.cancel()
+
+	if s.server != nil {
+		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+		if err := s.server.Shutdown(ctx); chk.E(err) {
+			return err
+		}
+	}
+
+	s.wg.Wait()
+	log.I.F("NIP-46 bunker server stopped")
+	return nil
+}
+
+// handleWebSocket handles WebSocket connections for NIP-46.
+func (s *Server) handleWebSocket(w http.ResponseWriter, r *http.Request) {
+	conn, err := upgrader.Upgrade(w, r, nil)
+	if err != nil {
+		log.E.F("bunker websocket upgrade failed: %v", err)
+		return
+	}
+
+	session := NewSession(s.ctx, conn, s.relaySigner, s.relayPubkey)
+
+	// Register session
+	s.sessionsMu.Lock()
+	s.sessions[session.ID] = session
+	s.sessionsMu.Unlock()
+
+	// Handle session
+	session.Handle()
+
+	// Unregister session
+	s.sessionsMu.Lock()
+	delete(s.sessions, session.ID)
+	s.sessionsMu.Unlock()
+}
+
+// SessionCount returns the number of active sessions.
+func (s *Server) SessionCount() int {
+	s.sessionsMu.RLock()
+	defer s.sessionsMu.RUnlock()
+	return len(s.sessions)
+}
+
+// RelayPubkeyHex returns the relay's public key as hex.
+func (s *Server) RelayPubkeyHex() string {
+	return fmt.Sprintf("%x", s.relayPubkey)
+}
+
+// NIP46Request represents a NIP-46 request from a client.
+type NIP46Request struct {
+	ID     string          `json:"id"`
+	Method string          `json:"method"`
+	Params json.RawMessage `json:"params"`
+}
+
+// NIP46Response represents a NIP-46 response to a client.
+type NIP46Response struct {
+	ID     string `json:"id"`
+	Result any    `json:"result,omitempty"`
+	Error  string `json:"error,omitempty"`
+}

pkg/bunker/session.go

@@ -0,0 +1,240 @@
+package bunker
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/gorilla/websocket"
+	"lukechampine.com/frand"
+	"lol.mleku.dev/log"
+
+	"git.mleku.dev/mleku/nostr/encoders/event"
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"git.mleku.dev/mleku/nostr/encoders/timestamp"
+	"git.mleku.dev/mleku/nostr/interfaces/signer"
+)
+
+// NIP-46 method names
+const (
+	MethodConnect      = "connect"
+	MethodGetPublicKey = "get_public_key"
+	MethodSignEvent    = "sign_event"
+	MethodNIP04Encrypt = "nip04_encrypt"
+	MethodNIP04Decrypt = "nip04_decrypt"
+	MethodNIP44Encrypt = "nip44_encrypt"
+	MethodNIP44Decrypt = "nip44_decrypt"
+	MethodPing         = "ping"
+)
+
+// Session represents a NIP-46 client session.
+type Session struct {
+	ID            string
+	conn          *websocket.Conn
+	ctx           context.Context
+	cancel        context.CancelFunc
+	relaySigner   signer.I
+	relayPubkey   []byte
+	authenticated bool
+	clientPubkey  []byte // Client's pubkey after connect
+}
+
+// NewSession creates a new bunker session.
+func NewSession(parentCtx context.Context, conn *websocket.Conn, relaySigner signer.I, relayPubkey []byte) *Session {
+	ctx, cancel := context.WithCancel(parentCtx)
+
+	// Generate random session ID
+	idBytes := make([]byte, 16)
+	frand.Read(idBytes)
+
+	return &Session{
+		ID:          hex.Enc(idBytes),
+		conn:        conn,
+		ctx:         ctx,
+		cancel:      cancel,
+		relaySigner: relaySigner,
+		relayPubkey: relayPubkey,
+	}
+}
+
+// Handle processes messages from the client.
+func (s *Session) Handle() {
+	defer s.conn.Close()
+	defer s.cancel()
+
+	log.D.F("bunker session started: %s", s.ID[:8])
+
+	for {
+		select {
+		case <-s.ctx.Done():
+			return
+		default:
+		}
+
+		// Set read deadline
+		s.conn.SetReadDeadline(time.Now().Add(60 * time.Second))
+
+		// Read message
+		_, msg, err := s.conn.ReadMessage()
+		if err != nil {
+			if websocket.IsCloseError(err, websocket.CloseNormalClosure, websocket.CloseGoingAway) {
+				log.D.F("bunker session closed normally: %s", s.ID[:8])
+			} else {
+				log.D.F("bunker session read error: %v", err)
+			}
+			return
+		}
+
+		// Parse request
+		var req NIP46Request
+		if err := json.Unmarshal(msg, &req); err != nil {
+			s.sendError("", "invalid request format")
+			continue
+		}
+
+		// Handle request
+		resp := s.handleRequest(&req)
+		s.sendResponse(resp)
+	}
+}
+
+// handleRequest processes a NIP-46 request.
+func (s *Session) handleRequest(req *NIP46Request) *NIP46Response {
+	switch req.Method {
+	case MethodConnect:
+		return s.handleConnect(req)
+	case MethodGetPublicKey:
+		return s.handleGetPublicKey(req)
+	case MethodSignEvent:
+		return s.handleSignEvent(req)
+	case MethodPing:
+		return s.handlePing(req)
+	case MethodNIP44Encrypt, MethodNIP44Decrypt, MethodNIP04Encrypt, MethodNIP04Decrypt:
+		// Encryption/decryption not supported in this bunker implementation
+		return &NIP46Response{
+			ID:    req.ID,
+			Error: "encryption methods not supported",
+		}
+	default:
+		return &NIP46Response{
+			ID:    req.ID,
+			Error: fmt.Sprintf("unsupported method: %s", req.Method),
+		}
+	}
+}
+
+// handleConnect handles the connect method.
+func (s *Session) handleConnect(req *NIP46Request) *NIP46Response {
+	// Parse params: [pubkey, secret?]
+	var params []string
+	if err := json.Unmarshal(req.Params, &params); err != nil {
+		return &NIP46Response{ID: req.ID, Error: "invalid params"}
+	}
+
+	if len(params) < 1 {
+		return &NIP46Response{ID: req.ID, Error: "missing pubkey"}
+	}
+
+	pubkeyHex := params[0]
+	clientPubkey, err := hex.Dec(pubkeyHex)
+	if err != nil || len(clientPubkey) != 32 {
+		return &NIP46Response{ID: req.ID, Error: "invalid pubkey"}
+	}
+
+	s.clientPubkey = clientPubkey
+	s.authenticated = true
+
+	log.I.F("bunker session authenticated: %s (client=%s...)",
+		s.ID[:8], pubkeyHex[:16])
+
+	return &NIP46Response{
+		ID:     req.ID,
+		Result: "ack",
+	}
+}
+
+// handleGetPublicKey returns the relay's public key.
+func (s *Session) handleGetPublicKey(req *NIP46Request) *NIP46Response {
+	return &NIP46Response{
+		ID:     req.ID,
+		Result: hex.Enc(s.relayPubkey),
+	}
+}
+
+// handleSignEvent signs an event with the relay's key.
+func (s *Session) handleSignEvent(req *NIP46Request) *NIP46Response {
+	if !s.authenticated {
+		return &NIP46Response{ID: req.ID, Error: "not authenticated"}
+	}
+
+	// Parse event from params
+	var params []json.RawMessage
+	if err := json.Unmarshal(req.Params, &params); err != nil {
+		return &NIP46Response{ID: req.ID, Error: "invalid params"}
+	}
+
+	if len(params) < 1 {
+		return &NIP46Response{ID: req.ID, Error: "missing event"}
+	}
+
+	// Parse the event
+	ev := &event.E{}
+	if err := json.Unmarshal(params[0], ev); err != nil {
+		return &NIP46Response{ID: req.ID, Error: "invalid event"}
+	}
+
+	// Set pubkey to relay's pubkey
+	copy(ev.Pubkey[:], s.relayPubkey)
+
+	// Set created_at if not set
+	if ev.CreatedAt == 0 {
+		ev.CreatedAt = timestamp.Now().V
+	}
+
+	// Sign the event
+	if err := ev.Sign(s.relaySigner); err != nil {
+		return &NIP46Response{ID: req.ID, Error: fmt.Sprintf("signing failed: %v", err)}
+	}
+
+	// Return signed event as JSON
+	signedJSON, err := json.Marshal(ev)
+	if err != nil {
+		return &NIP46Response{ID: req.ID, Error: "marshal failed"}
+	}
+
+	return &NIP46Response{
+		ID:     req.ID,
+		Result: string(signedJSON),
+	}
+}
+
+// handlePing responds to ping requests.
+func (s *Session) handlePing(req *NIP46Request) *NIP46Response {
+	return &NIP46Response{
+		ID:     req.ID,
+		Result: "pong",
+	}
+}
+
+// sendResponse sends a response to the client.
+func (s *Session) sendResponse(resp *NIP46Response) {
+	data, err := json.Marshal(resp)
+	if err != nil {
+		log.E.F("bunker marshal error: %v", err)
+		return
+	}
+
+	s.conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
+	if err := s.conn.WriteMessage(websocket.TextMessage, data); err != nil {
+		log.E.F("bunker write error: %v", err)
+	}
+}
+
+// sendError sends an error response.
+func (s *Session) sendError(id, msg string) {
+	s.sendResponse(&NIP46Response{
+		ID:    id,
+		Error: msg,
+	})
+}

pkg/database/wireguard.go

@@ -0,0 +1,591 @@
+//go:build !(js && wasm)
+
+package database
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/dgraph-io/badger/v4"
+	"lol.mleku.dev/chk"
+	"lol.mleku.dev/log"
+
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"next.orly.dev/pkg/wireguard"
+)
+
+// Key prefixes for WireGuard data
+const (
+	wgServerKeyPrefix  = "wg:server:key"  // Server's WireGuard private key
+	wgSubnetSeedPrefix = "wg:subnet:seed" // Seed for deterministic subnet generation
+	wgPeerPrefix       = "wg:peer:"       // Peer data by Nostr pubkey hex
+	wgSequenceKey      = "wg:seq"         // Badger sequence key for subnet allocation
+	wgRevokedPrefix    = "wg:revoked:"    // Revoked keypairs by Nostr pubkey hex
+	wgAccessLogPrefix  = "wg:accesslog:"  // Access log for obsolete addresses
+)
+
+// WireGuardPeer stores WireGuard peer information in the database.
+type WireGuardPeer struct {
+	NostrPubkey  []byte `json:"nostr_pubkey"`   // User's Nostr pubkey (32 bytes)
+	WGPrivateKey []byte `json:"wg_private_key"` // WireGuard private key (32 bytes)
+	WGPublicKey  []byte `json:"wg_public_key"`  // WireGuard public key (32 bytes)
+	Sequence     uint32 `json:"sequence"`       // Sequence number for subnet derivation
+	CreatedAt    int64  `json:"created_at"`     // Unix timestamp
+}
+
+// WireGuardRevokedKey stores a revoked/old WireGuard keypair for audit purposes.
+type WireGuardRevokedKey struct {
+	NostrPubkey  []byte `json:"nostr_pubkey"`   // User's Nostr pubkey (32 bytes)
+	WGPublicKey  []byte `json:"wg_public_key"`  // Revoked WireGuard public key (32 bytes)
+	Sequence     uint32 `json:"sequence"`       // Sequence number (subnet)
+	CreatedAt    int64  `json:"created_at"`     // When the key was originally created
+	RevokedAt    int64  `json:"revoked_at"`     // When the key was revoked
+	AccessCount  int    `json:"access_count"`   // Number of access attempts since revocation
+	LastAccessAt int64  `json:"last_access_at"` // Last access attempt timestamp (0 if never)
+}
+
+// WireGuardAccessLog records an access attempt to an obsolete address.
+type WireGuardAccessLog struct {
+	NostrPubkey []byte `json:"nostr_pubkey"`  // User's Nostr pubkey
+	WGPublicKey []byte `json:"wg_public_key"` // The obsolete public key used
+	Sequence    uint32 `json:"sequence"`      // Subnet sequence
+	Timestamp   int64  `json:"timestamp"`     // When the access occurred
+	RemoteAddr  string `json:"remote_addr"`   // Remote IP address
+}
+
+// ServerIP returns the derived server IP for this peer's subnet.
+func (p *WireGuardPeer) ServerIP(pool *wireguard.SubnetPool) string {
+	subnet := pool.SubnetForSequence(p.Sequence)
+	return subnet.ServerIP.String()
+}
+
+// ClientIP returns the derived client IP for this peer's subnet.
+func (p *WireGuardPeer) ClientIP(pool *wireguard.SubnetPool) string {
+	subnet := pool.SubnetForSequence(p.Sequence)
+	return subnet.ClientIP.String()
+}
+
+// GetWireGuardServerKey retrieves the WireGuard server private key.
+func (d *D) GetWireGuardServerKey() (key []byte, err error) {
+	err = d.DB.View(func(txn *badger.Txn) error {
+		item, err := txn.Get([]byte(wgServerKeyPrefix))
+		if errors.Is(err, badger.ErrKeyNotFound) {
+			return err
+		}
+		if err != nil {
+			return err
+		}
+		return item.Value(func(val []byte) error {
+			key = make([]byte, len(val))
+			copy(key, val)
+			return nil
+		})
+	})
+	return
+}
+
+// SetWireGuardServerKey stores the WireGuard server private key.
+func (d *D) SetWireGuardServerKey(key []byte) error {
+	if len(key) != 32 {
+		return fmt.Errorf("invalid key length: %d (expected 32)", len(key))
+	}
+	return d.DB.Update(func(txn *badger.Txn) error {
+		return txn.Set([]byte(wgServerKeyPrefix), key)
+	})
+}
+
+// GetOrCreateWireGuardServerKey retrieves or creates the WireGuard server key.
+func (d *D) GetOrCreateWireGuardServerKey() (key []byte, err error) {
+	// Try to get existing key
+	if key, err = d.GetWireGuardServerKey(); err == nil && len(key) == 32 {
+		return key, nil
+	}
+	if err != nil && !errors.Is(err, badger.ErrKeyNotFound) {
+		return nil, err
+	}
+
+	// Generate new keypair
+	privateKey, publicKey, err := wireguard.GenerateKeyPair()
+	if err != nil {
+		return nil, fmt.Errorf("failed to generate WireGuard keypair: %w", err)
+	}
+
+	// Store the private key
+	if err = d.SetWireGuardServerKey(privateKey); chk.E(err) {
+		return nil, err
+	}
+
+	log.I.F("generated new WireGuard server key (pubkey=%s...)", hex.Enc(publicKey[:8]))
+	return privateKey, nil
+}
+
+// GetSubnetSeed retrieves the subnet pool seed.
+func (d *D) GetSubnetSeed() (seed []byte, err error) {
+	err = d.DB.View(func(txn *badger.Txn) error {
+		item, err := txn.Get([]byte(wgSubnetSeedPrefix))
+		if errors.Is(err, badger.ErrKeyNotFound) {
+			return err
+		}
+		if err != nil {
+			return err
+		}
+		return item.Value(func(val []byte) error {
+			seed = make([]byte, len(val))
+			copy(seed, val)
+			return nil
+		})
+	})
+	return
+}
+
+// SetSubnetSeed stores the subnet pool seed.
+func (d *D) SetSubnetSeed(seed []byte) error {
+	if len(seed) != 32 {
+		return fmt.Errorf("invalid seed length: %d (expected 32)", len(seed))
+	}
+	return d.DB.Update(func(txn *badger.Txn) error {
+		return txn.Set([]byte(wgSubnetSeedPrefix), seed)
+	})
+}
+
+// GetOrCreateSubnetPool creates or restores a subnet pool from the database.
+func (d *D) GetOrCreateSubnetPool(baseNetwork string) (*wireguard.SubnetPool, error) {
+	// Try to get existing seed
+	seed, err := d.GetSubnetSeed()
+	if err != nil && !errors.Is(err, badger.ErrKeyNotFound) {
+		return nil, err
+	}
+
+	var pool *wireguard.SubnetPool
+
+	if len(seed) == 32 {
+		// Restore pool with existing seed
+		pool, err = wireguard.NewSubnetPoolWithSeed(baseNetwork, seed)
+		if err != nil {
+			return nil, err
+		}
+		log.D.F("restored subnet pool with existing seed")
+	} else {
+		// Create new pool with random seed
+		pool, err = wireguard.NewSubnetPool(baseNetwork)
+		if err != nil {
+			return nil, err
+		}
+
+		// Store the new seed
+		if err = d.SetSubnetSeed(pool.Seed()); err != nil {
+			return nil, fmt.Errorf("failed to store subnet seed: %w", err)
+		}
+		log.I.F("generated new subnet pool seed")
+	}
+
+	// Restore existing allocations from database
+	peers, err := d.GetAllWireGuardPeers()
+	if err != nil {
+		return nil, fmt.Errorf("failed to load existing peers: %w", err)
+	}
+
+	for _, peer := range peers {
+		pool.RestoreAllocation(hex.Enc(peer.NostrPubkey), peer.Sequence)
+	}
+
+	if len(peers) > 0 {
+		log.D.F("restored %d subnet allocations", len(peers))
+	}
+
+	return pool, nil
+}
+
+// GetWireGuardPeer retrieves a WireGuard peer by Nostr pubkey.
+func (d *D) GetWireGuardPeer(nostrPubkey []byte) (peer *WireGuardPeer, err error) {
+	key := append([]byte(wgPeerPrefix), []byte(hex.Enc(nostrPubkey))...)
+
+	err = d.DB.View(func(txn *badger.Txn) error {
+		item, err := txn.Get(key)
+		if errors.Is(err, badger.ErrKeyNotFound) {
+			return err
+		}
+		if err != nil {
+			return err
+		}
+		return item.Value(func(val []byte) error {
+			peer = &WireGuardPeer{}
+			return json.Unmarshal(val, peer)
+		})
+	})
+	return
+}
+
+// GetOrCreateWireGuardPeer retrieves or creates a WireGuard peer.
+// The pool is used for subnet derivation from the sequence number.
+func (d *D) GetOrCreateWireGuardPeer(nostrPubkey []byte, pool *wireguard.SubnetPool) (peer *WireGuardPeer, err error) {
+	// Try to get existing peer
+	if peer, err = d.GetWireGuardPeer(nostrPubkey); err == nil {
+		return peer, nil
+	}
+	if err != nil && !errors.Is(err, badger.ErrKeyNotFound) {
+		return nil, err
+	}
+
+	// Generate new WireGuard keypair
+	privateKey, publicKey, err := wireguard.GenerateKeyPair()
+	if err != nil {
+		return nil, fmt.Errorf("failed to generate WireGuard keypair: %w", err)
+	}
+
+	// Get next sequence number from Badger's sequence
+	seq64, err := d.GetNextWGSequence()
+	if err != nil {
+		return nil, fmt.Errorf("failed to allocate sequence: %w", err)
+	}
+	seq := uint32(seq64)
+
+	// Register allocation with pool for in-memory tracking
+	pubkeyHex := hex.Enc(nostrPubkey)
+	pool.RestoreAllocation(pubkeyHex, seq)
+
+	peer = &WireGuardPeer{
+		NostrPubkey:  nostrPubkey,
+		WGPrivateKey: privateKey,
+		WGPublicKey:  publicKey,
+		Sequence:     seq,
+		CreatedAt:    time.Now().Unix(),
+	}
+
+	// Store peer data
+	if err = d.setWireGuardPeer(peer); err != nil {
+		return nil, err
+	}
+
+	subnet := pool.SubnetForSequence(seq)
+	log.I.F("created WireGuard peer: nostr=%s... -> subnet %s/%s (seq=%d)",
+		hex.Enc(nostrPubkey[:8]), subnet.ServerIP, subnet.ClientIP, seq)
+
+	return peer, nil
+}
+
+// RegenerateWireGuardPeer generates a new keypair for an existing peer.
+// The sequence number (and thus subnet) is preserved.
+// The old keypair is archived for audit purposes.
+func (d *D) RegenerateWireGuardPeer(nostrPubkey []byte, pool *wireguard.SubnetPool) (peer *WireGuardPeer, err error) {
+	// Get existing peer to preserve sequence
+	existing, err := d.GetWireGuardPeer(nostrPubkey)
+	if err != nil {
+		return nil, err
+	}
+
+	// Archive the old keypair for audit purposes
+	if err = d.ArchiveRevokedKey(existing); err != nil {
+		log.W.F("failed to archive revoked key: %v", err)
+		// Continue anyway - this is audit logging, not critical
+	}
+
+	// Generate new WireGuard keypair
+	privateKey, publicKey, err := wireguard.GenerateKeyPair()
+	if err != nil {
+		return nil, fmt.Errorf("failed to generate WireGuard keypair: %w", err)
+	}
+
+	peer = &WireGuardPeer{
+		NostrPubkey:  nostrPubkey,
+		WGPrivateKey: privateKey,
+		WGPublicKey:  publicKey,
+		Sequence:     existing.Sequence, // Keep same sequence (same subnet)
+		CreatedAt:    time.Now().Unix(),
+	}
+
+	// Store updated peer data
+	if err = d.setWireGuardPeer(peer); err != nil {
+		return nil, err
+	}
+
+	subnet := pool.SubnetForSequence(peer.Sequence)
+	log.I.F("regenerated WireGuard peer: nostr=%s... -> subnet %s/%s (old key archived)",
+		hex.Enc(nostrPubkey[:8]), subnet.ServerIP, subnet.ClientIP)
+
+	return peer, nil
+}
+
+// DeleteWireGuardPeer removes a WireGuard peer from the database.
+// Note: The sequence number is not recycled to prevent subnet reuse.
+func (d *D) DeleteWireGuardPeer(nostrPubkey []byte) error {
+	peerKey := append([]byte(wgPeerPrefix), []byte(hex.Enc(nostrPubkey))...)
+
+	return d.DB.Update(func(txn *badger.Txn) error {
+		if err := txn.Delete(peerKey); err != nil && !errors.Is(err, badger.ErrKeyNotFound) {
+			return err
+		}
+		return nil
+	})
+}
+
+// GetAllWireGuardPeers returns all WireGuard peers.
+func (d *D) GetAllWireGuardPeers() (peers []*WireGuardPeer, err error) {
+	prefix := []byte(wgPeerPrefix)
+
+	err = d.DB.View(func(txn *badger.Txn) error {
+		opts := badger.DefaultIteratorOptions
+		opts.Prefix = prefix
+		it := txn.NewIterator(opts)
+		defer it.Close()
+
+		for it.Seek(prefix); it.ValidForPrefix(prefix); it.Next() {
+			item := it.Item()
+			err := item.Value(func(val []byte) error {
+				peer := &WireGuardPeer{}
+				if err := json.Unmarshal(val, peer); err != nil {
+					return err
+				}
+				peers = append(peers, peer)
+				return nil
+			})
+			if err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+	return
+}
+
+// setWireGuardPeer stores a WireGuard peer in the database.
+func (d *D) setWireGuardPeer(peer *WireGuardPeer) error {
+	data, err := json.Marshal(peer)
+	if err != nil {
+		return fmt.Errorf("failed to marshal peer: %w", err)
+	}
+
+	peerKey := append([]byte(wgPeerPrefix), []byte(hex.Enc(peer.NostrPubkey))...)
+
+	return d.DB.Update(func(txn *badger.Txn) error {
+		return txn.Set(peerKey, data)
+	})
+}
+
+// GetNextWGSequence retrieves and increments the sequence counter using Badger's Sequence.
+func (d *D) GetNextWGSequence() (seq uint64, err error) {
+	// Get a sequence with bandwidth 1 (allocate 1 number at a time)
+	badgerSeq, err := d.DB.GetSequence([]byte(wgSequenceKey), 1)
+	if err != nil {
+		return 0, fmt.Errorf("failed to get sequence: %w", err)
+	}
+	defer badgerSeq.Release()
+
+	seq, err = badgerSeq.Next()
+	if err != nil {
+		return 0, fmt.Errorf("failed to get next sequence number: %w", err)
+	}
+	return seq, nil
+}
+
+// ArchiveRevokedKey stores a revoked keypair for audit purposes.
+func (d *D) ArchiveRevokedKey(peer *WireGuardPeer) error {
+	revoked := &WireGuardRevokedKey{
+		NostrPubkey: peer.NostrPubkey,
+		WGPublicKey: peer.WGPublicKey,
+		Sequence:    peer.Sequence,
+		CreatedAt:   peer.CreatedAt,
+		RevokedAt:   time.Now().Unix(),
+		AccessCount: 0,
+		LastAccessAt: 0,
+	}
+
+	data, err := json.Marshal(revoked)
+	if err != nil {
+		return fmt.Errorf("failed to marshal revoked key: %w", err)
+	}
+
+	// Key: wg:revoked:<pubkey-hex>:<revoked-timestamp>
+	keyStr := fmt.Sprintf("%s%s:%d", wgRevokedPrefix, hex.Enc(peer.NostrPubkey), revoked.RevokedAt)
+
+	return d.DB.Update(func(txn *badger.Txn) error {
+		return txn.Set([]byte(keyStr), data)
+	})
+}
+
+// GetRevokedKeys returns all revoked keys for a user.
+func (d *D) GetRevokedKeys(nostrPubkey []byte) (keys []*WireGuardRevokedKey, err error) {
+	prefix := []byte(wgRevokedPrefix + hex.Enc(nostrPubkey) + ":")
+
+	err = d.DB.View(func(txn *badger.Txn) error {
+		opts := badger.DefaultIteratorOptions
+		opts.Prefix = prefix
+		it := txn.NewIterator(opts)
+		defer it.Close()
+
+		for it.Seek(prefix); it.ValidForPrefix(prefix); it.Next() {
+			item := it.Item()
+			err := item.Value(func(val []byte) error {
+				key := &WireGuardRevokedKey{}
+				if err := json.Unmarshal(val, key); err != nil {
+					return err
+				}
+				keys = append(keys, key)
+				return nil
+			})
+			if err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+	return
+}
+
+// GetAllRevokedKeys returns all revoked keys across all users (admin view).
+func (d *D) GetAllRevokedKeys() (keys []*WireGuardRevokedKey, err error) {
+	prefix := []byte(wgRevokedPrefix)
+
+	err = d.DB.View(func(txn *badger.Txn) error {
+		opts := badger.DefaultIteratorOptions
+		opts.Prefix = prefix
+		it := txn.NewIterator(opts)
+		defer it.Close()
+
+		for it.Seek(prefix); it.ValidForPrefix(prefix); it.Next() {
+			item := it.Item()
+			err := item.Value(func(val []byte) error {
+				key := &WireGuardRevokedKey{}
+				if err := json.Unmarshal(val, key); err != nil {
+					return err
+				}
+				keys = append(keys, key)
+				return nil
+			})
+			if err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+	return
+}
+
+// LogObsoleteAccess records an access attempt to an obsolete WireGuard address.
+func (d *D) LogObsoleteAccess(nostrPubkey, wgPubkey []byte, sequence uint32, remoteAddr string) error {
+	now := time.Now().Unix()
+
+	logEntry := &WireGuardAccessLog{
+		NostrPubkey: nostrPubkey,
+		WGPublicKey: wgPubkey,
+		Sequence:    sequence,
+		Timestamp:   now,
+		RemoteAddr:  remoteAddr,
+	}
+
+	data, err := json.Marshal(logEntry)
+	if err != nil {
+		return fmt.Errorf("failed to marshal access log: %w", err)
+	}
+
+	// Key: wg:accesslog:<pubkey-hex>:<timestamp>
+	keyStr := fmt.Sprintf("%s%s:%d", wgAccessLogPrefix, hex.Enc(nostrPubkey), now)
+
+	return d.DB.Update(func(txn *badger.Txn) error {
+		return txn.Set([]byte(keyStr), data)
+	})
+}
+
+// GetAccessLogs returns access logs for a user.
+func (d *D) GetAccessLogs(nostrPubkey []byte) (logs []*WireGuardAccessLog, err error) {
+	prefix := []byte(wgAccessLogPrefix + hex.Enc(nostrPubkey) + ":")
+
+	err = d.DB.View(func(txn *badger.Txn) error {
+		opts := badger.DefaultIteratorOptions
+		opts.Prefix = prefix
+		it := txn.NewIterator(opts)
+		defer it.Close()
+
+		for it.Seek(prefix); it.ValidForPrefix(prefix); it.Next() {
+			item := it.Item()
+			err := item.Value(func(val []byte) error {
+				logEntry := &WireGuardAccessLog{}
+				if err := json.Unmarshal(val, logEntry); err != nil {
+					return err
+				}
+				logs = append(logs, logEntry)
+				return nil
+			})
+			if err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+	return
+}
+
+// GetAllAccessLogs returns all access logs (admin view).
+func (d *D) GetAllAccessLogs() (logs []*WireGuardAccessLog, err error) {
+	prefix := []byte(wgAccessLogPrefix)
+
+	err = d.DB.View(func(txn *badger.Txn) error {
+		opts := badger.DefaultIteratorOptions
+		opts.Prefix = prefix
+		it := txn.NewIterator(opts)
+		defer it.Close()
+
+		for it.Seek(prefix); it.ValidForPrefix(prefix); it.Next() {
+			item := it.Item()
+			err := item.Value(func(val []byte) error {
+				logEntry := &WireGuardAccessLog{}
+				if err := json.Unmarshal(val, logEntry); err != nil {
+					return err
+				}
+				logs = append(logs, logEntry)
+				return nil
+			})
+			if err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+	return
+}
+
+// IncrementRevokedKeyAccess updates the access count for a revoked key.
+func (d *D) IncrementRevokedKeyAccess(nostrPubkey, wgPubkey []byte) error {
+	// Find and update the matching revoked key
+	prefix := []byte(wgRevokedPrefix + hex.Enc(nostrPubkey) + ":")
+	wgPubkeyHex := hex.Enc(wgPubkey)
+	now := time.Now().Unix()
+
+	return d.DB.Update(func(txn *badger.Txn) error {
+		opts := badger.DefaultIteratorOptions
+		opts.Prefix = prefix
+		it := txn.NewIterator(opts)
+		defer it.Close()
+
+		for it.Seek(prefix); it.ValidForPrefix(prefix); it.Next() {
+			item := it.Item()
+			key := item.KeyCopy(nil)
+
+			err := item.Value(func(val []byte) error {
+				revoked := &WireGuardRevokedKey{}
+				if err := json.Unmarshal(val, revoked); err != nil {
+					return err
+				}
+
+				// Check if this is the matching revoked key
+				if hex.Enc(revoked.WGPublicKey) == wgPubkeyHex {
+					revoked.AccessCount++
+					revoked.LastAccessAt = now
+
+					data, err := json.Marshal(revoked)
+					if err != nil {
+						return err
+					}
+					return txn.Set(key, data)
+				}
+				return nil
+			})
+			if err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+}

pkg/version/version

@@ -1 +1 @@
-v0.39.3
+v0.40.0

pkg/wireguard/errors.go

@@ -0,0 +1,23 @@
+package wireguard
+
+import "errors"
+
+var (
+	// ErrInvalidKeyLength is returned when a key is not exactly 32 bytes.
+	ErrInvalidKeyLength = errors.New("invalid key length: must be 32 bytes")
+
+	// ErrServerNotRunning is returned when an operation requires a running server.
+	ErrServerNotRunning = errors.New("wireguard server not running")
+
+	// ErrEndpointRequired is returned when WireGuard is enabled but no endpoint is set.
+	ErrEndpointRequired = errors.New("ORLY_WG_ENDPOINT is required when WireGuard is enabled")
+
+	// ErrInvalidNetwork is returned when the network CIDR is invalid.
+	ErrInvalidNetwork = errors.New("invalid network CIDR")
+
+	// ErrPeerNotFound is returned when a peer lookup fails.
+	ErrPeerNotFound = errors.New("peer not found")
+
+	// ErrIPExhausted is returned when no more IPs are available in the network.
+	ErrIPExhausted = errors.New("no more IP addresses available in network")
+)

pkg/wireguard/keygen.go

@@ -0,0 +1,42 @@
+// Package wireguard provides an embedded WireGuard VPN server for secure
+// NIP-46 bunker access. It uses wireguard-go with gVisor netstack for
+// userspace networking (no root required).
+package wireguard
+
+import (
+	"crypto/rand"
+
+	"golang.org/x/crypto/curve25519"
+)
+
+// GenerateKeyPair generates a new Curve25519 keypair for WireGuard.
+// Returns the private key and public key as 32-byte slices.
+func GenerateKeyPair() (privateKey, publicKey []byte, err error) {
+	privateKey = make([]byte, 32)
+	if _, err = rand.Read(privateKey); err != nil {
+		return nil, nil, err
+	}
+
+	// Curve25519 clamping (required by WireGuard spec)
+	privateKey[0] &= 248
+	privateKey[31] &= 127
+	privateKey[31] |= 64
+
+	// Derive public key from private key
+	publicKey = make([]byte, 32)
+	curve25519.ScalarBaseMult((*[32]byte)(publicKey), (*[32]byte)(privateKey))
+
+	return privateKey, publicKey, nil
+}
+
+// DerivePublicKey derives the public key from a private key.
+func DerivePublicKey(privateKey []byte) (publicKey []byte, err error) {
+	if len(privateKey) != 32 {
+		return nil, ErrInvalidKeyLength
+	}
+
+	publicKey = make([]byte, 32)
+	curve25519.ScalarBaseMult((*[32]byte)(publicKey), (*[32]byte)(privateKey))
+
+	return publicKey, nil
+}

pkg/wireguard/server.go

@@ -0,0 +1,281 @@
+package wireguard
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/hex"
+	"fmt"
+	"net"
+	"net/netip"
+	"sync"
+
+	"golang.zx2c4.com/wireguard/conn"
+	"golang.zx2c4.com/wireguard/device"
+	"golang.zx2c4.com/wireguard/tun"
+	"golang.zx2c4.com/wireguard/tun/netstack"
+	"lol.mleku.dev/log"
+)
+
+// Config holds the WireGuard server configuration.
+type Config struct {
+	Port       int    // UDP port for WireGuard (default 51820)
+	Endpoint   string // Public IP/domain for clients to connect to
+	PrivateKey []byte // Server's 32-byte Curve25519 private key
+	Network    string // CIDR for internal network (e.g., "10.73.0.0/16")
+	ServerIP   string // Server's internal IP (e.g., "10.73.0.1")
+}
+
+// Peer represents a WireGuard peer (client).
+type Peer struct {
+	NostrPubkey []byte // User's Nostr pubkey (32 bytes)
+	WGPublicKey []byte // WireGuard public key (32 bytes)
+	AssignedIP  string // Assigned internal IP
+}
+
+// Server manages the embedded WireGuard VPN server.
+type Server struct {
+	cfg       *Config
+	device    *device.Device
+	tun       *netstack.Net
+	tunDev    tun.Device
+	publicKey []byte
+
+	peers   map[string]*Peer // WG pubkey (base64) -> Peer
+	peersMu sync.RWMutex
+
+	ctx     context.Context
+	cancel  context.CancelFunc
+	running bool
+	mu      sync.RWMutex
+}
+
+// New creates a new WireGuard server with the given configuration.
+func New(cfg *Config) (*Server, error) {
+	if cfg.Endpoint == "" {
+		return nil, ErrEndpointRequired
+	}
+
+	// Parse network CIDR to validate it
+	_, _, err := net.ParseCIDR(cfg.Network)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrInvalidNetwork, err)
+	}
+
+	// Default server IP if not set
+	if cfg.ServerIP == "" {
+		cfg.ServerIP = "10.73.0.1"
+	}
+
+	// Derive public key from private key
+	publicKey, err := DerivePublicKey(cfg.PrivateKey)
+	if err != nil {
+		return nil, fmt.Errorf("failed to derive public key: %w", err)
+	}
+
+	return &Server{
+		cfg:       cfg,
+		publicKey: publicKey,
+		peers:     make(map[string]*Peer),
+	}, nil
+}
+
+// Start initializes and starts the WireGuard server.
+func (s *Server) Start() error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if s.running {
+		return nil
+	}
+
+	s.ctx, s.cancel = context.WithCancel(context.Background())
+
+	// Parse server IP
+	serverAddr, err := netip.ParseAddr(s.cfg.ServerIP)
+	if err != nil {
+		return fmt.Errorf("invalid server IP: %w", err)
+	}
+
+	// Create netstack TUN device (userspace, no root required)
+	s.tunDev, s.tun, err = netstack.CreateNetTUN(
+		[]netip.Addr{serverAddr},
+		[]netip.Addr{}, // No DNS servers
+		1420,           // MTU
+	)
+	if err != nil {
+		return fmt.Errorf("failed to create netstack TUN: %w", err)
+	}
+
+	// Create WireGuard device
+	s.device = device.NewDevice(
+		s.tunDev,
+		conn.NewDefaultBind(),
+		device.NewLogger(device.LogLevelSilent, "wg"),
+	)
+
+	// Configure device with server private key and listen port
+	privateKeyHex := hex.EncodeToString(s.cfg.PrivateKey)
+	ipcConfig := fmt.Sprintf("private_key=%s\nlisten_port=%d\n",
+		privateKeyHex,
+		s.cfg.Port,
+	)
+
+	if err = s.device.IpcSet(ipcConfig); err != nil {
+		s.device.Close()
+		return fmt.Errorf("failed to configure WireGuard device: %w", err)
+	}
+
+	// Bring up the device
+	if err = s.device.Up(); err != nil {
+		s.device.Close()
+		return fmt.Errorf("failed to bring up WireGuard device: %w", err)
+	}
+
+	s.running = true
+	log.I.F("WireGuard server started on UDP port %d", s.cfg.Port)
+	log.I.F("WireGuard server public key: %s", base64.StdEncoding.EncodeToString(s.publicKey))
+	log.I.F("WireGuard internal network: %s (server: %s)", s.cfg.Network, s.cfg.ServerIP)
+
+	return nil
+}
+
+// Stop shuts down the WireGuard server.
+func (s *Server) Stop() error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if !s.running {
+		return nil
+	}
+
+	if s.cancel != nil {
+		s.cancel()
+	}
+
+	if s.device != nil {
+		s.device.Close()
+	}
+
+	s.running = false
+	log.I.F("WireGuard server stopped")
+
+	return nil
+}
+
+// IsRunning returns whether the server is currently running.
+func (s *Server) IsRunning() bool {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.running
+}
+
+// ServerPublicKey returns the server's WireGuard public key.
+func (s *Server) ServerPublicKey() []byte {
+	return s.publicKey
+}
+
+// Endpoint returns the configured endpoint address.
+func (s *Server) Endpoint() string {
+	return fmt.Sprintf("%s:%d", s.cfg.Endpoint, s.cfg.Port)
+}
+
+// GetNetstack returns the netstack networking interface.
+// This is used by the bunker to listen on the WireGuard network.
+func (s *Server) GetNetstack() *netstack.Net {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.tun
+}
+
+// ServerIP returns the server's internal IP address.
+func (s *Server) ServerIP() string {
+	return s.cfg.ServerIP
+}
+
+// AddPeer adds a new peer to the WireGuard server.
+func (s *Server) AddPeer(nostrPubkey, wgPublicKey []byte, assignedIP string) error {
+	s.mu.RLock()
+	if !s.running {
+		s.mu.RUnlock()
+		return ErrServerNotRunning
+	}
+	s.mu.RUnlock()
+
+	// Encode WG public key as hex for IPC
+	wgPubkeyHex := hex.EncodeToString(wgPublicKey)
+	wgPubkeyBase64 := base64.StdEncoding.EncodeToString(wgPublicKey)
+
+	// Configure peer in WireGuard device
+	ipcConfig := fmt.Sprintf(
+		"public_key=%s\nallowed_ip=%s/32\n",
+		wgPubkeyHex,
+		assignedIP,
+	)
+
+	if err := s.device.IpcSet(ipcConfig); err != nil {
+		return fmt.Errorf("failed to add peer: %w", err)
+	}
+
+	// Track peer
+	s.peersMu.Lock()
+	s.peers[wgPubkeyBase64] = &Peer{
+		NostrPubkey: nostrPubkey,
+		WGPublicKey: wgPublicKey,
+		AssignedIP:  assignedIP,
+	}
+	s.peersMu.Unlock()
+
+	log.I.F("WireGuard peer added: %s -> %s", wgPubkeyBase64[:16]+"...", assignedIP)
+
+	return nil
+}
+
+// RemovePeer removes a peer from the WireGuard server.
+func (s *Server) RemovePeer(wgPublicKey []byte) error {
+	s.mu.RLock()
+	if !s.running {
+		s.mu.RUnlock()
+		return ErrServerNotRunning
+	}
+	s.mu.RUnlock()
+
+	wgPubkeyHex := hex.EncodeToString(wgPublicKey)
+	wgPubkeyBase64 := base64.StdEncoding.EncodeToString(wgPublicKey)
+
+	// Remove peer from WireGuard device
+	ipcConfig := fmt.Sprintf(
+		"public_key=%s\nremove=true\n",
+		wgPubkeyHex,
+	)
+
+	if err := s.device.IpcSet(ipcConfig); err != nil {
+		return fmt.Errorf("failed to remove peer: %w", err)
+	}
+
+	// Remove from tracking
+	s.peersMu.Lock()
+	delete(s.peers, wgPubkeyBase64)
+	s.peersMu.Unlock()
+
+	log.I.F("WireGuard peer removed: %s", wgPubkeyBase64[:16]+"...")
+
+	return nil
+}
+
+// GetPeer returns a peer by their WireGuard public key.
+func (s *Server) GetPeer(wgPublicKey []byte) (*Peer, bool) {
+	wgPubkeyBase64 := base64.StdEncoding.EncodeToString(wgPublicKey)
+
+	s.peersMu.RLock()
+	defer s.peersMu.RUnlock()
+
+	peer, ok := s.peers[wgPubkeyBase64]
+	return peer, ok
+}
+
+// PeerCount returns the number of active peers.
+func (s *Server) PeerCount() int {
+	s.peersMu.RLock()
+	defer s.peersMu.RUnlock()
+	return len(s.peers)
+}

pkg/wireguard/subnet_pool.go

@@ -0,0 +1,184 @@
+package wireguard
+
+import (
+	"crypto/sha256"
+	"encoding/binary"
+	"fmt"
+	"net/netip"
+	"sync"
+
+	"lukechampine.com/frand"
+)
+
+// Subnet represents a /31 point-to-point subnet.
+type Subnet struct {
+	ServerIP netip.Addr // Even address (server side)
+	ClientIP netip.Addr // Odd address (client side)
+}
+
+// SubnetPool manages deterministic /31 subnet generation from a seed.
+// Given the same seed and sequence number, the same subnet is always generated.
+type SubnetPool struct {
+	seed       [32]byte       // Random seed for deterministic generation
+	basePrefix netip.Prefix   // e.g., 10.0.0.0/8
+	maxSeq     uint32         // Current highest sequence number
+	assigned   map[string]uint32 // Client pubkey hex -> sequence number
+	mu         sync.RWMutex
+}
+
+// NewSubnetPool creates a subnet pool with a new random seed.
+func NewSubnetPool(baseNetwork string) (*SubnetPool, error) {
+	prefix, err := netip.ParsePrefix(baseNetwork)
+	if err != nil {
+		return nil, fmt.Errorf("invalid base network: %w", err)
+	}
+
+	var seed [32]byte
+	frand.Read(seed[:])
+
+	return &SubnetPool{
+		seed:       seed,
+		basePrefix: prefix,
+		maxSeq:     0,
+		assigned:   make(map[string]uint32),
+	}, nil
+}
+
+// NewSubnetPoolWithSeed creates a subnet pool with an existing seed.
+func NewSubnetPoolWithSeed(baseNetwork string, seed []byte) (*SubnetPool, error) {
+	prefix, err := netip.ParsePrefix(baseNetwork)
+	if err != nil {
+		return nil, fmt.Errorf("invalid base network: %w", err)
+	}
+
+	if len(seed) != 32 {
+		return nil, fmt.Errorf("seed must be 32 bytes, got %d", len(seed))
+	}
+
+	pool := &SubnetPool{
+		basePrefix: prefix,
+		maxSeq:     0,
+		assigned:   make(map[string]uint32),
+	}
+	copy(pool.seed[:], seed)
+
+	return pool, nil
+}
+
+// Seed returns the pool's seed for persistence.
+func (p *SubnetPool) Seed() []byte {
+	return p.seed[:]
+}
+
+// deriveSubnet deterministically generates a /31 subnet from seed + sequence.
+func (p *SubnetPool) deriveSubnet(seq uint32) Subnet {
+	// Hash seed + sequence to get deterministic randomness
+	h := sha256.New()
+	h.Write(p.seed[:])
+	binary.Write(h, binary.BigEndian, seq)
+	hash := h.Sum(nil)
+
+	// Use first 4 bytes as offset within the prefix
+	offset := binary.BigEndian.Uint32(hash[:4])
+
+	// Calculate available address space
+	bits := p.basePrefix.Bits()
+	availableBits := uint32(32 - bits)
+	maxOffset := uint32(1) << availableBits
+
+	// Make offset even (for /31 alignment) and within range
+	offset = (offset % (maxOffset / 2)) * 2
+
+	// Calculate server IP (even) and client IP (odd)
+	baseAddr := p.basePrefix.Addr()
+	baseBytes := baseAddr.As4()
+	baseVal := uint32(baseBytes[0])<<24 | uint32(baseBytes[1])<<16 |
+		uint32(baseBytes[2])<<8 | uint32(baseBytes[3])
+
+	serverVal := baseVal + offset
+	clientVal := serverVal + 1
+
+	serverBytes := [4]byte{
+		byte(serverVal >> 24), byte(serverVal >> 16),
+		byte(serverVal >> 8), byte(serverVal),
+	}
+	clientBytes := [4]byte{
+		byte(clientVal >> 24), byte(clientVal >> 16),
+		byte(clientVal >> 8), byte(clientVal),
+	}
+
+	return Subnet{
+		ServerIP: netip.AddrFrom4(serverBytes),
+		ClientIP: netip.AddrFrom4(clientBytes),
+	}
+}
+
+// ServerIPs returns server-side IPs for sequences 0 to maxSeq (for netstack).
+func (p *SubnetPool) ServerIPs() []netip.Addr {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+
+	if p.maxSeq == 0 {
+		return nil
+	}
+
+	ips := make([]netip.Addr, p.maxSeq)
+	for seq := uint32(0); seq < p.maxSeq; seq++ {
+		subnet := p.deriveSubnet(seq)
+		ips[seq] = subnet.ServerIP
+	}
+	return ips
+}
+
+// GetSubnet returns the subnet for a client, or nil if not assigned.
+func (p *SubnetPool) GetSubnet(clientPubkeyHex string) *Subnet {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+
+	if seq, ok := p.assigned[clientPubkeyHex]; ok {
+		subnet := p.deriveSubnet(seq)
+		return &subnet
+	}
+	return nil
+}
+
+// GetSequence returns the sequence number for a client, or -1 if not assigned.
+func (p *SubnetPool) GetSequence(clientPubkeyHex string) int {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+
+	if seq, ok := p.assigned[clientPubkeyHex]; ok {
+		return int(seq)
+	}
+	return -1
+}
+
+// RestoreAllocation restores a previously saved allocation.
+func (p *SubnetPool) RestoreAllocation(clientPubkeyHex string, seq uint32) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	p.assigned[clientPubkeyHex] = seq
+	if seq >= p.maxSeq {
+		p.maxSeq = seq + 1
+	}
+}
+
+// MaxSequence returns the current max sequence number.
+func (p *SubnetPool) MaxSequence() uint32 {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	return p.maxSeq
+}
+
+// AllocatedCount returns the number of allocated subnets.
+func (p *SubnetPool) AllocatedCount() int {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	return len(p.assigned)
+}
+
+// SubnetForSequence returns the subnet for a given sequence number.
+func (p *SubnetPool) SubnetForSequence(seq uint32) Subnet {
+	return p.deriveSubnet(seq)
+}