Skip to content

PasteFerry (隔空贴): clipboard and file sync across macOS, Windows and Linux. Direct-first, end-to-end encrypted. Optional official access: no server to host. Independent self-hosting remains available.

56.6 KB
Raw Blame
// Package peers 管理已配对设备:配对流程、在线状态、信令收发。
//
// 信令有两条通道:信令服务器(可选,跨网络时用)和局域网(同一网络里直接收发)。
// 两条通道并存,信令同时从两条路发出,接收方按 nonce 去重;
// 任意一条通道报告对方在线,就算在线。配对结果两条通道通用。
package peers

import (
	"context"
	"crypto/ed25519"
	"crypto/rand"
	"encoding/hex"
	"errors"
	"fmt"
	"log/slog"
	"net/http"
	"net/netip"
	"runtime"
	"sort"
	"sync"
	"time"

	"github.com/baiyuze/pasteferry/client-core/internal/config"
	"github.com/baiyuze/pasteferry/client-core/internal/gateway"
	"github.com/baiyuze/pasteferry/client-core/internal/identity"
	"github.com/baiyuze/pasteferry/client-core/internal/store"
	"github.com/baiyuze/pasteferry/client-core/internal/transport/lan"
	"github.com/baiyuze/pasteferry/client-core/internal/transport/p2p"
	"github.com/baiyuze/pasteferry/client-core/internal/transport/signaling"
	"github.com/baiyuze/pasteferry/client-core/internal/transport/signed"
	"github.com/baiyuze/pasteferry/proto/deviceid"
	pb "github.com/baiyuze/pasteferry/proto/gen/pasteferry/v1"
	"github.com/baiyuze/pasteferry/proto/pairingcode"
)

// pendingPair 是一次等待用户核对指纹的配对。
//
// 配对必须由双方各自确认指纹后才落库:信令服务器(或同一网络里的其他人)
// 能替换转发中的公钥,但无法让两端显示出相同的指纹——用户的肉眼核对是防中间人的最后一道闸。
type pendingPair struct {
	session   string
	peer      store.Device
	expiresAt time.Time
	// initiated 表示本机是配对码的发起方(对方兑换了我的码)
	initiated bool
	// addrs 是在局域网里配对时对方的地址,确认后写进地址簿
	addrs []string

	// 这次是配对还是加好友(lan.IntentDevice / lan.IntentFriend),对方的用途(不知道时为空)
	// 和名片。两边的用途一致才继续,见 friends.go
	intent        string
	peerIntent    string
	peerCard      *pb.FriendCard
	intentKnown   chan struct{} // 知道对方的用途后关闭
	intentDone    bool
	intentReplyAt time.Time
	mismatch      error
	// 加好友:两边的用户各自点了「添加」(1)或「取消」(-1)
	localDecision int
	peerDecision  int
}

const pendingTTL = 5 * time.Minute

// activeCode 是本机正在显示的配对码。连着服务器时它同时在服务器和局域网两边开放,
// 一边用掉之后,另一边的兑换一律不认。
type activeCode struct {
	code    string
	expires time.Time
	used    bool
	intent  string // 配对码还是好友码
}

type redeemResult struct {
	ev  *pb.PairingRedeemResponse
	err error
}

type Manager struct {
	identity *identity.Identity
	store    *store.Store
	log      *slog.Logger

	loadConfig func() config.Config
	// 配对关系或在线状态变化时通知上层(推给 UI)
	onDeviceChanged func(*pb.Device)
	// 信令连上/断开、对端上下线时通知上层,UI 的连接状态靠它刷新
	onStatusChanged func()
	// 收到对端信令(SDP/candidate),M2 的 WebRTC 层在此接管
	onSignal func(from string, msg *pb.SignalMessage)
	// onPeerReady 见 Options.OnPeerReady
	onPeerReady func(deviceID string)

	client   *signaling.Client
	lan      *lan.Transport
	verifier *signed.Verifier
	p2p      *p2p.Manager
	gateway  *gateway.Client

	mu sync.RWMutex
	// 不能在持有 mu 时调用 lan 里会加它自己的锁的方法(Reachable 除外):
	// lan 持锁期间会回调这里
	known map[string]store.Device // 已配对设备
	// serverOnline 是信令服务器报告的在线状态;局域网的在线状态在 lan 里
	serverOnline map[string]bool
	conn         map[string]p2p.ConnState // P2P 连接状态(直连/中转)
	// features 是对端在 PeerFeatures 里声明的功能,见 wire.proto。没收到过的设备没有条目。
	// 启动时从数据库读回上次的声明,所以重启后不必等连上就知道对方支持什么
	features map[string]map[string]bool
	// peerVersion 是对端声明里带的版本号(2.5.4 起),旧版本没有
	peerVersion map[string]string
	// declared 记下本次连接里对端是否发过声明;legacy 是连上 legacyWait 后仍没声明、判定为旧版本的设备
	declared map[string]bool
	legacy   map[string]bool
	// connectionEpoch 让上一轮连接的延迟检查不能影响刚重建的连接。
	connectionEpoch map[string]uint64
	// appVersion 是本机的版本号,随功能声明发给对端
	appVersion string
	// sendFiles 报告本机有没有隔空传送,见 Options.SendFiles
	sendFiles bool
	// noFeatures 让测试模拟不发功能声明的旧版本
	noFeatures bool

	// 好友(对方的一台电脑),见 friends.go
	contacts map[string]store.Contact
	// 已成为好友后回复确认的时间;避免两端把确认回执互相无限回发。
	confirmReplyAt map[string]time.Time
	// 「所有人」模式下认识的陌生设备,只在内存里
	strangers map[string]store.Contact
	// 删除了好友、还没告诉对方的:设备 ID → 对方公钥(验对方回执的签名)
	notices map[string][]byte
	// 和好友、陌生设备最近一次收发的时间,空闲的断开
	lastUse map[string]time.Time
	// 用途不一致而作废的配对会话,ConfirmPairing 据此给出原因
	mismatched map[string]error

	card            func() *pb.FriendCard
	avatar          func() []byte
	saveAvatar      func(deviceID string, jpeg []byte) (string, error)
	onFriendChanged func(*pb.Friend)
	onFriendRemoved func(deviceID string)
	onFriendRequest func(*pb.FriendRequest)
	onOtherReady    func(deviceID string)
	shareableStream func(label string) bool
	inUse           func(deviceID string) bool
	pending         map[string]*pendingPair // session -> 待确认配对
	// stashed 暂存配对确认前到达的信令,按对端 device_id 归集
	stashed map[string][]*pb.SignalMessage
	active  *activeCode
	// 等服务器回音的配对请求(服务器的回复是异步的,靠这些通道回传结果)
	codeWaiters   []chan pairingCode
	redeemWaiters []chan redeemResult
}

type pairingCode struct {
	code      string
	expiresAt time.Time
	err       error
}

type Options struct {
	Identity        *identity.Identity
	Store           *store.Store
	Logger          *slog.Logger
	LoadConfig      func() config.Config
	OnDeviceChanged func(*pb.Device)
	OnStatusChanged func()
	OnSignal        func(from string, msg *pb.SignalMessage)
	// OnPeerMessage / OnPeerStream 是 P2P 数据面的入口,M4 的同步逻辑挂在这里
	OnPeerMessage func(deviceID string, msg *pb.PeerMessage)
	OnPeerStream  func(deviceID, label string, stream *p2p.Stream)
	// OnPeerReady 在与某台设备的 P2P 连接建立或恢复时调用(同步引擎据此补发)
	OnPeerReady func(deviceID string)
	// StatePath 保存网络出口历史的文件,见 p2p/egress_history.go
	StatePath string
	// LANPort / LANDiscovery 供测试替换局域网通道的端口和发现方式,默认 8788 与 mDNS
	LANPort      int
	LANDiscovery lan.Discovery
	// AppVersion 是本机的版本号,随功能声明发给对端,对端用它提示「需要更新到哪个版本」
	AppVersion string
	// SendFiles 报告本机是否组装了隔空传送(internal/send)。只有真的有这个功能的客户端
	// 才能声明 send_files_v1,见 featuresFor。手机端一期没有隔空传送(design/phone-sync.md 3.1.2),
	// 打开它会让电脑把文件发给手机、然后一直等不到应答
	SendFiles bool

	// 好友(2.6.0)。Card 是发给好友的本机名片;Avatar 是本机头像(JPEG,没有时为空);
	// SaveAvatar 把好友发来的头像重新编码后存下,返回存放的路径;jpeg 为空时删掉存着的
	Card       func() *pb.FriendCard
	Avatar     func() []byte
	SaveAvatar func(deviceID string, jpeg []byte) (string, error)
	// OnFriendChanged 好友加上或状态变化;OnFriendRemoved 好友被删除(任一方)或加好友时对方取消了;
	// OnFriendRequest 有人兑换了本机的好友码,界面弹出确认框
	OnFriendChanged func(*pb.Friend)
	OnFriendRemoved func(deviceID string)
	OnFriendRequest func(*pb.FriendRequest)
	// OnOtherReady 与好友或陌生设备的连接建立时调用(隔空传送据此开始发);OnPeerReady 只给自己的设备
	OnOtherReady func(deviceID string)
	// ShareableStream 判断好友、陌生设备开来的数据流能不能收(隔空传送的),其余一律关掉
	ShareableStream func(label string) bool
	// InUse 报告与某台电脑之间是否还有传输在进行,空闲断开好友连接时据此跳过
	InUse func(deviceID string) bool
}

// legacyWait 是连上以后等对端功能声明的时间。旧版本(2.5.0 之前)从不发声明,
// 等这么久还没有就判定为旧版本;在此之前只能说「还不知道」
var legacyWait = 5 * time.Second

func NewManager(opts Options) (*Manager, error) {
	log := opts.Logger
	if log == nil {
		log = slog.Default()
	}

	m := &Manager{
		identity:        opts.Identity,
		store:           opts.Store,
		log:             log,
		loadConfig:      opts.LoadConfig,
		onDeviceChanged: opts.OnDeviceChanged,
		onStatusChanged: opts.OnStatusChanged,
		onSignal:        opts.OnSignal,
		onPeerReady:     opts.OnPeerReady,
		known:           make(map[string]store.Device),
		serverOnline:    make(map[string]bool),
		conn:            make(map[string]p2p.ConnState),
		features:        make(map[string]map[string]bool),
		peerVersion:     make(map[string]string),
		declared:        make(map[string]bool),
		legacy:          make(map[string]bool),
		connectionEpoch: make(map[string]uint64),
		appVersion:      opts.AppVersion,
		sendFiles:       opts.SendFiles,
		contacts:        make(map[string]store.Contact),
		confirmReplyAt:  make(map[string]time.Time),
		strangers:       make(map[string]store.Contact),
		notices:         make(map[string][]byte),
		lastUse:         make(map[string]time.Time),
		mismatched:      make(map[string]error),
		card:            opts.Card,
		avatar:          opts.Avatar,
		saveAvatar:      opts.SaveAvatar,
		onFriendChanged: opts.OnFriendChanged,
		onFriendRemoved: opts.OnFriendRemoved,
		onFriendRequest: opts.OnFriendRequest,
		onOtherReady:    opts.OnOtherReady,
		shareableStream: opts.ShareableStream,
		inUse:           opts.InUse,
		pending:         make(map[string]*pendingPair),
		stashed:         make(map[string][]*pb.SignalMessage),
	}

	devices, err := opts.Store.ListDevices()
	if err != nil {
		return nil, fmt.Errorf("读取已配对设备: %w", err)
	}
	for _, d := range devices {
		m.known[d.ID] = d
		if len(d.Features) > 0 {
			m.features[d.ID] = featureSet(d.Features)
			m.peerVersion[d.ID] = d.AppVersion
		}
	}
	if err := m.loadContacts(); err != nil {
		return nil, err
	}

	m.gateway, err = gateway.NewClient(opts.Identity, gateway.OfficialBaseURL, func(u gateway.Usage) {
		m.notifyStatus()
		if m.p2p != nil && u.Available && u.Remaining > 0 && u.Reason == "" {
			m.p2p.OfficialAllowanceChanged()
		}
	})
	if err != nil {
		return nil, err
	}
	m.gateway.SetEnabled(opts.LoadConfig().Official())
	m.p2p = p2p.NewManager(p2p.ManagerOptions{
		Gateway:        m.gateway,
		Official:       func() bool { return opts.LoadConfig().Official() },
		OfficialOnline: func(id string) bool { m.mu.RLock(); defer m.mu.RUnlock(); return m.serverOnline[id] },
		SelfID:         opts.Identity.DeviceID,
		Logger:         log,
		SendSignal:     m.sendSignal,
		OnState:        m.handleP2PState,
		OnMessage: func(id string, msg *pb.PeerMessage) {
			if role := m.Role(id); role != RoleSelf {
				if role == "" || m.handleOtherMessage(id, role, msg) {
					return
				}
				if opts.OnPeerMessage != nil {
					opts.OnPeerMessage(id, msg)
				}
				return
			}
			if display := msg.GetDisplay(); display != nil {
				m.updatePeerDisplay(id, display)
				return
			}
			if f := msg.GetFeatures(); f != nil {
				m.updatePeerFeatures(id, f)
				return
			}
			if opts.OnPeerMessage != nil {
				opts.OnPeerMessage(id, msg)
			}
		},
		OnStream: func(id, label string, stream *p2p.Stream) {
			if role := m.Role(id); role != RoleSelf {
				// 好友、陌生设备只能开隔空传送的数据流
				if role == "" || m.shareableStream == nil || !m.shareableStream(label) {
					m.log.Warn("关掉非自己设备开来的数据流", "device", id, "role", role, "label", label)
					stream.Close()
					return
				}
				m.touch(id)
			}
			if opts.OnPeerStream != nil {
				opts.OnPeerStream(id, label, stream)
			} else {
				stream.Close()
			}
		},
		StatePath: opts.StatePath,
		// 公共 STUN 服务器 IP 分散,能探测到更多出口;用户可以在设置里关掉。
		// 没有服务器时只在局域网里连,探测出口没有用,还会把公网 IP 暴露给公共服务器
		ProbeServers: func() []string {
			cfg := opts.LoadConfig()
			if cfg.OnlyOwnSTUN || cfg.EffectiveSignalingURL() == "" {
				return nil
			}
			return p2p.DefaultProbeServers
		},
	})

	m.verifier = signed.NewVerifier(opts.Identity.DeviceID, m.publicKeyOf)
	m.lan = lan.New(lan.Options{
		Identity:  opts.Identity,
		Logger:    log,
		Port:      opts.LANPort,
		Discovery: opts.LANDiscovery,
		Verifier:  m.verifier,
		Book:      opts.Store,
		Peers:     m.lanPeerIDs,
		Connected: func(id string) bool { return connected(m.p2p.State(id)) },
		DeviceInfo: func() (string, string) {
			return m.loadConfig().DeviceName, runtime.GOOS
		},
		OnSignal:       m.handleSignal,
		OnReachable:    m.handleLANReachable,
		OnRestarted:    m.handlePeerRestarted,
		AcceptPair:     m.acceptLANPair,
		AcceptNearby:   m.acceptNearby,
		AcceptStranger: m.acceptStranger,
		OnChange:       m.notifyStatus,
	})

	m.client = signaling.New(signaling.Options{
		Identity: opts.Identity,
		URL:      opts.LoadConfig().EffectiveSignalingURL(),
		DialHeaders: func(url string) http.Header {
			if opts.LoadConfig().Official() && url == gateway.OfficialSignalURL {
				return gateway.SignalHeaders(opts.Identity)
			}
			return nil
		},
		Logger:      log,
		Verifier:    m.verifier,
		PublicKeyOf: m.publicKeyOf,
		DeviceInfo:  m.deviceInfo,
		Handlers: signaling.Handlers{
			OnConnected:       m.handleConnected,
			OnDisconnected:    m.handleDisconnected,
			OnPresence:        m.handlePresence,
			OnSignal:          m.handleSignal,
			OnPairingCreated:  m.handlePairingCreated,
			OnPairingRedeemed: m.handlePairingRedeemed,
			OnPairingResult:   m.handlePairingResult,
			OnIceConfig: func(servers []*pb.IceServer) {
				m.p2p.SetICEServers(servers)
			},
			OnServerError: m.handleServerError,
		},
	})
	return m, nil
}

func (m *Manager) Run(ctx context.Context) {
	if !m.loadConfig().LANDisabled {
		if err := m.lan.Start(); err != nil {
			m.log.Warn("局域网直连启动失败", "err", err)
		}
	}
	m.ApplyEveryone()
	go m.gcPending(ctx)
	go m.gateway.Run(ctx)
	go m.reconnectLoop(ctx)
	m.client.Run(ctx)
	m.lan.Stop()
}

// SetLANEnabled 在用户于设置里开关局域网发现后调用,立即生效。
func (m *Manager) SetLANEnabled(enabled bool) {
	if enabled {
		if err := m.lan.Start(); err != nil {
			m.log.Warn("局域网直连启动失败", "err", err)
		}
		return
	}
	m.lan.Stop()
}

// reconnectLoop 定期把"在线但尚未建立 P2P 通道"的对端重新连上。
//
// 单靠上线通知触发连接是不够的:配对刚完成时两端确认有先后,
// 先确认的一方发出的 offer 会被后确认的一方当作未配对消息丢弃;
// 网络切换、信令重连也会让某次握手失败。有了这道巡检,
// 连接状态最终总会收敛,而不需要用户手动重启。
func (m *Manager) reconnectLoop(ctx context.Context) {
	t := time.NewTicker(10 * time.Second)
	defer t.Stop()
	features := time.NewTicker(time.Minute)
	defer features.Stop()
	idle := time.NewTicker(30 * time.Second)
	defer idle.Stop()

	for {
		select {
		case <-ctx.Done():
			return
		case <-idle.C:
			m.dropIdleOthers()
			m.forgetIdleStrangers()
			m.sendNotices()
		case <-t.C:
			m.connectPending(ctx)
		case <-features.C:
			// 功能声明不能只发一次:早到或切换连接时丢失后也能自行恢复。
			m.BroadcastFeatures()
		}
	}
}

// connectPending 对所有在线但未连通的对端发起连接。
func (m *Manager) connectPending(ctx context.Context) {
	m.mu.RLock()
	var candidates []string
	now := time.Now()
	for id := range m.known {
		if m.isOnlineLocked(id) && m.p2p.State(id) == p2p.StateOffline {
			candidates = append(candidates, id)
		}
	}
	for _, others := range []map[string]store.Contact{m.contacts, m.strangers} {
		for id := range others {
			// 失败的握手、刚断掉的连接继续重试;已经空闲断开的好友不常连。
			if m.isOnlineLocked(id) && m.p2p.State(id) == p2p.StateOffline &&
				(now.Sub(m.lastUse[id]) < friendIdle || (m.inUse != nil && m.inUse(id))) {
				candidates = append(candidates, id)
			}
		}
	}
	m.mu.RUnlock()

	for _, id := range candidates {
		connectCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
		if err := m.p2p.RetryDirect(connectCtx, id); err != nil {
			m.log.Debug("重连失败,稍后重试", "device", id, "err", err)
		}
		cancel()
	}
}

// Connected 报告是否连着信令服务器。
func (m *Manager) Connected() bool { return m.client.Connected() }

// ServerConfigured 报告设置里是否填了服务器地址。没填时只在局域网里同步。
func (m *Manager) ServerConfigured() bool { return m.loadConfig().EffectiveSignalingURL() != "" }

// LANEnabled 报告局域网直连是否在运行。
func (m *Manager) LANEnabled() bool { return m.lan.Running() }

// LANBlocked 报告系统是否拦下了发往局域网的包(macOS 的本地网络权限)。
func (m *Manager) LANBlocked() bool { return m.lan.Blocked() }

// SetSignalingURL 在用户于设置里改了服务器地址后调用,立即重连。
func (m *Manager) SetSignalingURL(url string) {
	m.p2p.CloseAll()
	m.p2p.SetICEServers(nil)
	m.gateway.Close()
	m.gateway.SetEnabled(m.loadConfig().Official())
	m.client.SetURL(url)
}

func (m *Manager) OfficialUsage() *pb.OfficialUsage {
	if !m.loadConfig().Official() {
		return nil
	}
	u := m.gateway.Usage()
	return &pb.OfficialUsage{Available: u.Available, Day: u.Day, QuotaGroup: u.Group, UploadBytes: u.Upload, DownloadBytes: u.Download, LimitBytes: u.Limit, RemainingBytes: u.Remaining, ResetAtUnix: u.ResetAt, UpdatedAtUnix: u.UpdatedAt, Reason: u.Reason}
}

// 本机支持的功能,随 PeerFeatures 告诉对端
const (
	FeatureSendFiles    = "send_files_v1"
	FeatureSendFilesOff = "send_files_off" // 能接收隔空传送,但用户关掉了
	// 隔空传送能走局域网 TCP 快速通道(2.5.1),见 internal/transport/lantcp
	FeatureSendFilesTCP = "send_files_tcp_v1"
	// 真的实现了隔空传送的接收端(2.7.5)。手机端一期没有这个功能,但 2.7.4 及更早的
	// 安卓包会照抄桌面端的功能声明,所以手机平台只声明 send_files_v1 不算数,见 mobilePlatform
	FeatureSendFilesRecv = "send_files_recv_v1"
)

// mobilePlatform 报告这个平台是不是手机。
//
// 手机端一期不做隔空传送(design/phone-sync.md 3.1.2),但 2.7.4 及更早的安卓 App 用同一套
// peers.Manager,照抄了桌面端的功能声明。只改手机端挡不住已经装出去的包,所以收文件的判定
// 还要看平台:手机平台必须额外声明 FeatureSendFilesRecv 才算真的能收。
func mobilePlatform(platform string) bool {
	return platform == "android" || platform == "ios"
}

// ReceivesSendFiles 报告对端能不能收隔空传送:f 是它声明的功能,platform 是它的系统。
func ReceivesSendFiles(f map[string]bool, platform string) bool {
	if !f[FeatureSendFiles] && !f[FeatureSendFilesOff] {
		return false
	}
	return !mobilePlatform(platform) || f[FeatureSendFilesRecv]
}

func (m *Manager) featuresMessage() *pb.PeerMessage { return m.featuresFor(RoleSelf) }

func featureSet(names []string) map[string]bool {
	set := make(map[string]bool, len(names))
	for i, name := range names {
		if i >= 64 || len(name) > 64 {
			break
		}
		set[name] = true
	}
	return set
}

// BroadcastFeatures 在本机的功能开关变了以后(比如关掉了接收文件)告诉所有连着的设备。
func (m *Manager) BroadcastFeatures() {
	for _, id := range m.lanPeerIDs() {
		if connected(m.p2p.State(id)) {
			if role := m.Role(id); role != "" {
				_ = m.p2p.Send(id, m.featuresFor(role))
			}
		}
	}
}

func (m *Manager) updatePeerFeatures(id string, f *pb.PeerFeatures) {
	set := featureSet(f.GetFeatures())
	version := f.GetAppVersion()
	if len(version) > 32 {
		version = version[:32]
	}
	names := make([]string, 0, len(set))
	for name := range set {
		names = append(names, name)
	}
	sort.Strings(names)
	m.mu.Lock()
	role := m.roleLocked(id)
	reply := role != "" && !m.declared[id] && !m.noFeatures
	if role != "" {
		m.features[id] = set
		m.peerVersion[id] = version
		m.declared[id] = true
		delete(m.legacy, id)
	}
	c, isFriend := m.contacts[id]
	if isFriend {
		c.Features, c.AppVersion = names, version
		m.contacts[id] = c
	}
	m.mu.Unlock()
	switch role {
	case "":
		return
	case RoleSelf:
		if err := m.store.SetDeviceFeatures(id, names, version); err != nil {
			m.log.Warn("保存对端功能声明失败", "device", id, "err", err)
		}
	case RoleFriend:
		if err := m.store.PutContact(c); err != nil {
			m.log.Warn("保存好友的功能声明失败", "device", id, "err", err)
		}
	}
	if d, ok := m.device(id); ok {
		m.notify(d)
	}
	m.notifyFriend(id)
	// 首次收到声明时回一份,补救本端声明早到或切换连接时的丢失。
	if reply {
		_ = m.p2p.Send(id, m.featuresFor(role))
	}
}

// checkLegacy 在连上 legacyWait 之后检查对端发过功能声明没有:
// 还连着却一直没发,说明是不认识声明的旧版本。
func (m *Manager) checkLegacy(id string, epoch uint64) {
	m.mu.Lock()
	role := m.roleLocked(id)
	isLegacy := role != "" && m.connectionEpoch[id] == epoch && connected(m.conn[id]) && !m.declared[id]
	c := m.contacts[id]
	if isLegacy {
		m.legacy[id] = true
		// 上次存下的声明不再可信(对方装回了旧版本)
		delete(m.features, id)
		delete(m.peerVersion, id)
		if role == RoleFriend {
			c.Features, c.AppVersion = nil, ""
			m.contacts[id] = c
		}
	}
	m.mu.Unlock()
	if !isLegacy {
		return
	}
	switch role {
	case RoleSelf:
		if err := m.store.SetDeviceFeatures(id, nil, ""); err != nil {
			m.log.Warn("清除对端功能声明失败", "device", id, "err", err)
		}
	case RoleFriend:
		if err := m.store.PutContact(c); err != nil {
			m.log.Warn("清除好友功能声明失败", "device", id, "err", err)
		}
	}
	if d, ok := m.device(id); ok {
		m.notify(d)
	}
	m.notifyFriend(id)
}

// SendFilesSupport 返回对端能不能接收隔空传送:supported 为 false 说明是旧版本(或者还没收到它的声明),
// 或者对方是还没有隔空传送的手机;disabled 说明它关掉了接收。
func (m *Manager) SendFilesSupport(deviceID string) (supported, disabled bool) {
	m.mu.RLock()
	defer m.mu.RUnlock()
	f := m.features[deviceID]
	if !ReceivesSendFiles(f, m.platformLocked(deviceID)) {
		return false, false
	}
	return true, f[FeatureSendFilesOff]
}

// platformLocked 返回已认得的设备(配对设备、好友或陌生设备)的平台;都不认识时为空。
func (m *Manager) platformLocked(deviceID string) string {
	if d, ok := m.known[deviceID]; ok {
		return d.Platform
	}
	if c, ok := m.contacts[deviceID]; ok {
		return c.Platform
	}
	if c, ok := m.strangers[deviceID]; ok {
		return c.Platform
	}
	return ""
}

// HasFeature 报告对端是否声明了某项功能。
func (m *Manager) HasFeature(deviceID, feature string) bool {
	m.mu.RLock()
	defer m.mu.RUnlock()
	return m.features[deviceID][feature]
}

// FeaturesKnown 报告是否已经知道对端的功能;尚未声明与明确不支持是两种状态。
func (m *Manager) FeaturesKnown(deviceID string) bool {
	m.mu.RLock()
	defer m.mu.RUnlock()
	_, declared := m.features[deviceID]
	return declared || m.legacy[deviceID]
}

// ConnState 返回与某台设备的 P2P 连接状态。
func (m *Manager) ConnState(deviceID string) p2p.ConnState { return m.p2p.State(deviceID) }

// DeviceName 返回已配对设备的名字,没有这台设备时返回空字符串。
func (m *Manager) DeviceName(deviceID string) string {
	m.mu.RLock()
	defer m.mu.RUnlock()
	return m.known[deviceID].Name
}

func (m *Manager) updatePeerDisplay(id string, display *pb.PeerDisplay) {
	if len(display.GetName()) > 256 || len(display.GetPlatform()) > 32 {
		return
	}
	m.mu.Lock()
	d, ok := m.known[id]
	if ok && display.GetName() != "" {
		d.Name = display.GetName()
		d.Platform = display.GetPlatform()
		m.known[id] = d
	}
	m.mu.Unlock()
	if ok {
		_ = m.store.PutDevice(d)
		if p, ok := m.device(id); ok {
			m.notify(p)
		}
	}
}

// ─────────────────────── 信令回调 ───────────────────────

// publicKeyOf 供信令层验签。
//
// 除已配对设备外,也认待确认配对中的对端公钥——那把公钥已随配对流程
// 取得并校验过与 device_id 相符。能验签不等于信任:是否建立互信仍由
// 用户在 ConfirmPairing 里决定,这里只是让早到的信令不至于被直接丢弃。
func (m *Manager) publicKeyOf(deviceID string) ed25519.PublicKey {
	m.mu.RLock()
	defer m.mu.RUnlock()

	if d, ok := m.known[deviceID]; ok {
		return ed25519.PublicKey(d.PublicKey)
	}
	if c, ok := m.contacts[deviceID]; ok {
		return ed25519.PublicKey(c.PublicKey)
	}
	if c, ok := m.strangers[deviceID]; ok {
		return ed25519.PublicKey(c.PublicKey)
	}
	if key, ok := m.notices[deviceID]; ok {
		return ed25519.PublicKey(key)
	}
	for _, p := range m.pending {
		if p.peer.ID == deviceID {
			return ed25519.PublicKey(p.peer.PublicKey)
		}
	}
	return nil
}

func (m *Manager) deviceInfo() (name, platform string, paired []string) {
	m.mu.RLock()
	defer m.mu.RUnlock()
	// 好友的在线状态也要服务器推送
	ids := m.watchIDsLocked()
	if m.loadConfig().UsesOfficialEndpoint() {
		return "PasteFerry " + m.identity.DeviceID[:8], "", ids
	}
	return m.loadConfig().DeviceName, runtime.GOOS, ids
}

func (m *Manager) handleConnected() {
	m.log.Info("信令已连接", "url", m.client.URL())
	// 网络恢复后马上刷新官方额度;没开官方服务时网关客户端会忽略
	m.gateway.RefreshUsage()
	m.notifyAll()
	m.notifyStatus()
}

func (m *Manager) handleDisconnected(error) {
	m.mu.Lock()
	// 信令断开后无法从服务器得知对端状态;局域网那边的在线状态不受影响
	m.serverOnline = make(map[string]bool)
	m.mu.Unlock()
	m.notifyAll()
	m.notifyStatus()
}

func (m *Manager) handlePresence(deviceID string, online bool) {
	m.mu.Lock()
	m.serverOnline[deviceID] = online
	m.mu.Unlock()

	m.log.Debug("对端状态变化", "device", deviceID, "online", online)

	if online {
		m.connectIfOffline(deviceID)
		m.mu.RLock()
		_, notice := m.notices[deviceID]
		m.mu.RUnlock()
		if notice {
			go m.sendNotices()
		}
	} else if !m.lan.Reachable(deviceID) {
		// 服务器说对方下线了,局域网里也找不到:连接多半已经失效
		m.p2p.Disconnect(deviceID)
		m.mu.Lock()
		delete(m.conn, deviceID)
		m.mu.Unlock()
	}

	if d, ok := m.device(deviceID); ok {
		m.notify(d)
	}
	m.notifyFriend(deviceID)
	m.notifyStatus() // 在线对端数随之变化
}

// handleLANReachable 在局域网里找到或失去某台设备时调用。
// 失去时不主动断开:P2P 连接自己能发现对方没了,可能对方只是换了地址。
func (m *Manager) handleLANReachable(deviceID string, reachable bool) {
	if reachable {
		m.connectIfOffline(deviceID)
		m.mu.RLock()
		_, notice := m.notices[deviceID]
		m.mu.RUnlock()
		if notice {
			go m.sendNotices()
		}
	}
	if d, ok := m.device(deviceID); ok {
		m.notify(d)
	}
	m.notifyFriend(deviceID)
	m.notifyStatus()
}

// handlePeerRestarted:局域网里的某台设备重启过,本端的 P2P 连接已经失效,只是还没察觉。
// 立即丢掉重建;否则要等握手超时,对方又可能是应答方,只能干等本端来连。
func (m *Manager) handlePeerRestarted(deviceID string) {
	m.p2p.Disconnect(deviceID)
	m.mu.Lock()
	delete(m.conn, deviceID)
	m.mu.Unlock()
	m.connectIfOffline(deviceID)
}

// connectIfOffline 在对端上线时建立 P2P 通道,这样真正要传数据时已经就绪。
// 谁发起由 p2p.Manager 内部按 device_id 字典序决定,这里无脑调用即可。
func (m *Manager) connectIfOffline(deviceID string) {
	role := m.Role(deviceID)
	if role == "" {
		return
	}
	if role != RoleSelf {
		// 上线或重启后交换一次名片与功能声明,并为失败的握手保留重试窗口。
		m.touch(deviceID)
	}
	go func() {
		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
		defer cancel()

		// 只在完全没有连接时发起。正在握手中就不要插手——
		// 重置会换掉 ICE ufrag,让对端已经发出的 answer 全部失配。
		if m.p2p.State(deviceID) != p2p.StateOffline {
			return
		}
		if err := m.p2p.RetryDirect(ctx, deviceID); err != nil {
			m.log.Warn("建立 P2P 连接失败", "device", deviceID, "err", err)
		}
	}()
}

func (m *Manager) handleSignal(from string, msg *pb.SignalMessage) {
	// 加好友与删除好友的信令,不建立 P2P 连接
	switch p := msg.GetPayload().(type) {
	case *pb.SignalMessage_PairIntent:
		m.handlePairIntent(from, p.PairIntent)
		return
	case *pb.SignalMessage_FriendConfirm:
		m.handleFriendConfirm(from, p.FriendConfirm)
		return
	case *pb.SignalMessage_FriendRemove:
		m.handleFriendRemove(from, p.FriendRemove)
		return
	case *pb.SignalMessage_StrangerHello:
		return
	}

	m.mu.RLock()
	role := m.roleLocked(from)
	paired := role != ""
	pendingPair := !paired && m.hasPendingLocked(from)
	m.mu.RUnlock()

	if !paired {
		if pendingPair {
			// 配对尚未确认,但对方已经在发起连接了。
			//
			// 两端确认配对必然有先后,先确认的一方发出的 offer 一定早于
			// 后确认方建立互信。直接丢弃会让握手石沉大海,只能等超时重试;
			// 暂存下来在确认后重放,用户确认完就能立刻连上。
			m.stashSignal(from, msg)
			return
		}
		m.log.Warn("忽略未配对设备的信令", "from", from)
		return
	}

	m.dispatchSignal(from, msg)
}

func (m *Manager) dispatchSignal(from string, msg *pb.SignalMessage) {
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
	if err := m.p2p.HandleSignal(ctx, from, msg); err != nil {
		m.log.Warn("处理信令失败", "from", from, "err", err)
	}

	if m.onSignal != nil {
		m.onSignal(from, msg)
	}
}

func (m *Manager) hasPendingLocked(deviceID string) bool {
	for _, p := range m.pending {
		if p.peer.ID == deviceID {
			return true
		}
	}
	return false
}

// stashSignal 暂存配对确认前到达的信令。
func (m *Manager) stashSignal(from string, msg *pb.SignalMessage) {
	m.mu.Lock()
	defer m.mu.Unlock()

	// 只留少量:握手信令很快,堆积说明对端在异常重试,没必要全存
	const maxStashed = 32
	if len(m.stashed[from]) >= maxStashed {
		return
	}
	if m.stashed == nil {
		m.stashed = make(map[string][]*pb.SignalMessage)
	}
	m.stashed[from] = append(m.stashed[from], msg)
	m.log.Debug("暂存配对确认前到达的信令", "from", from, "已存", len(m.stashed[from]))
}

// replaySignals 在配对确认后重放暂存的信令。
func (m *Manager) replaySignals(from string) {
	m.mu.Lock()
	msgs := m.stashed[from]
	delete(m.stashed, from)
	m.mu.Unlock()

	if len(msgs) == 0 {
		return
	}
	m.log.Info("重放配对期间暂存的信令", "from", from, "条数", len(msgs))
	for _, msg := range msgs {
		m.dispatchSignal(from, msg)
	}
}

// handleP2PState 在直连/中转状态变化时刷新界面。
func (m *Manager) handleP2PState(deviceID string, state p2p.ConnState) {
	m.mu.Lock()
	prev := m.conn[deviceID]
	m.conn[deviceID] = state
	role := m.roleLocked(deviceID)
	if state != prev && (state == p2p.StateOffline || state == p2p.StateConnecting) {
		m.connectionEpoch[deviceID]++
		delete(m.declared, deviceID)
		delete(m.legacy, deviceID)
		// 连接恢复前,旧的「不能接收」不再作为更新依据;已知能接收的声明仍可用于排队发送。
		f := m.features[deviceID]
		if !ReceivesSendFiles(f, m.platformLocked(deviceID)) || (role != RoleSelf && !f[FeatureSendAsk]) {
			delete(m.features, deviceID)
			delete(m.peerVersion, deviceID)
		}
	}
	epoch := m.connectionEpoch[deviceID]
	if connected(state) && !connected(prev) {
		// 功能声明可能早于这个就绪回调到达,不能在这里把它重置。
		m.lastUse[deviceID] = time.Now()
	}
	m.mu.Unlock()
	if connected(state) && !connected(prev) {
		if role == RoleSelf {
			cfg := m.loadConfig()
			_ = m.p2p.Send(deviceID, &pb.PeerMessage{Payload: &pb.PeerMessage_Display{Display: &pb.PeerDisplay{Name: cfg.DeviceName, Platform: runtime.GOOS}}})
		} else {
			_ = m.p2p.Send(deviceID, &pb.PeerMessage{Payload: &pb.PeerMessage_FriendCard{FriendCard: m.selfCard()}})
		}
		if !m.noFeatures {
			_ = m.p2p.Send(deviceID, m.featuresFor(role))
		}
		time.AfterFunc(legacyWait, func() { m.checkLegacy(deviceID, epoch) })
	}

	m.log.Info("P2P 连接状态", "device", deviceID, "state", state)
	if d, ok := m.device(deviceID); ok {
		m.notify(d)
	}
	m.notifyFriend(deviceID)
	// 直连与中转之间切换不算重新连上
	if connected(state) && !connected(prev) {
		if role == RoleSelf && m.onPeerReady != nil {
			m.onPeerReady(deviceID)
		} else if role != RoleSelf && m.onOtherReady != nil {
			m.onOtherReady(deviceID)
		}
	}
}

func connected(s p2p.ConnState) bool {
	return s == p2p.StateDirect || s == p2p.StateRelay
}

// ErrNoRoute 表示对方既不在局域网里,本机也没连上服务器,信令无路可走。
var ErrNoRoute = errors.New("对方不在局域网里,也没有连上服务器")

// sendSignal 签一次名,从所有可用的通道发出去:局域网里能找到对方就走局域网,
// 连着服务器就也经服务器转发。接收方按 nonce 去重,只处理先到的那份。
func (m *Manager) sendSignal(ctx context.Context, to string, msg *pb.SignalMessage) error {
	s, err := signed.Sign(m.identity, to, msg)
	if err != nil {
		return err
	}
	sent := false
	var lastErr error
	if m.lan.Reachable(to) {
		if lastErr = m.lan.Send(to, s); lastErr == nil {
			sent = true
		}
	}
	if m.client.Connected() {
		if err := m.client.SendSigned(ctx, s); err == nil {
			sent = true
		} else {
			lastErr = err
		}
	}
	if sent {
		return nil
	}
	if lastErr == nil {
		lastErr = ErrNoRoute
	}
	return lastErr
}

// P2P 暴露数据面给上层(M4 的同步逻辑用)。
func (m *Manager) P2P() *p2p.Manager { return m.p2p }

func (m *Manager) handlePairingCreated(code string, expiresAt time.Time) {
	m.mu.Lock()
	waiters := m.codeWaiters
	m.codeWaiters = nil
	m.mu.Unlock()

	for _, ch := range waiters {
		ch <- pairingCode{code: code, expiresAt: expiresAt}
		close(ch)
	}
}

// handleServerError 把服务器对配对请求的拒绝交给正在等的调用方,免得它干等到超时。
func (m *Manager) handleServerError(code, msg string) {
	m.log.Warn("信令服务器错误", "code", code, "msg", msg)
	err := fmt.Errorf("服务器: %s", msg)
	m.mu.Lock()
	var codeWaiters []chan pairingCode
	var redeemWaiter chan redeemResult
	switch code {
	case "pairing_create_failed":
		codeWaiters, m.codeWaiters = m.codeWaiters, nil
	case "pairing_redeem_failed":
		if len(m.redeemWaiters) > 0 {
			redeemWaiter, m.redeemWaiters = m.redeemWaiters[0], m.redeemWaiters[1:]
		}
	}
	m.mu.Unlock()

	for _, ch := range codeWaiters {
		ch <- pairingCode{err: err}
		close(ch)
	}
	if redeemWaiter != nil {
		redeemWaiter <- redeemResult{err: ErrCodeRejected}
	}
}

// handlePairingRedeemed:本机是发起方,有人经服务器兑换了我的配对码。
// 同样要经用户确认指纹后才落库。
func (m *Manager) handlePairingRedeemed(ev *pb.PairingRedeemed) {
	m.mu.Lock()
	a := m.active
	if a != nil && a.used {
		m.mu.Unlock()
		m.log.Warn("忽略服务器转来的配对:这个配对码已在局域网里用掉", "peer", ev.GetPeerDeviceName())
		return
	}
	if a != nil {
		a.used = true
	}
	intent := lan.IntentDevice
	if a != nil && a.intent == lan.IntentFriend {
		intent = lan.IntentFriend
	}
	m.mu.Unlock()
	m.lan.ClosePairing()

	_, _ = m.addPendingFor(store.Device{
		ID:        ev.GetPeerDeviceId(),
		Name:      ev.GetPeerDeviceName(),
		Platform:  ev.GetPeerPlatform(),
		PublicKey: ev.GetPeerPublicKey(),
	}, true, nil, intent, "", nil)
}

// handlePairingResult:本机是兑换方,服务器回传了发起方信息。
func (m *Manager) handlePairingResult(ev *pb.PairingRedeemResponse) {
	m.mu.Lock()
	var ch chan redeemResult
	if len(m.redeemWaiters) > 0 {
		ch, m.redeemWaiters = m.redeemWaiters[0], m.redeemWaiters[1:]
	}
	m.mu.Unlock()
	if ch == nil {
		m.log.Warn("忽略迟到的配对结果", "peer", ev.GetPeerDeviceName())
		return
	}
	ch <- redeemResult{ev: ev}
}

// acceptLANPair:本机是发起方,有人在局域网里用对了我的配对码。
// 返回 false 表示这个码已经在服务器那边用掉了。
func (m *Manager) acceptLANPair(peer lan.PeerInfo) bool {
	m.mu.Lock()
	a := m.active
	if a == nil || a.used || time.Now().After(a.expires) {
		m.mu.Unlock()
		return false
	}
	intent := a.intent
	if intent == lan.IntentFriend && m.roleLocked(peer.ID) == RoleSelf {
		// 自己配对的设备来加好友:照常回复,由对方报「已经是你的设备」,本机不弹确认
		m.mu.Unlock()
		return true
	}
	a.used = true
	m.mu.Unlock()

	// 局域网里用途不一致的请求已经在 lan 里回绝了,这里两边一致
	_, err := m.addPendingFor(store.Device{
		ID:        peer.ID,
		Name:      peer.Name,
		Platform:  peer.Platform,
		PublicKey: peer.PublicKey,
	}, true, peer.Addrs, intent, peer.Intent, peer.Card)
	return err == nil
}

// acceptNearby:有人在「搜索附近设备」里点了本机。弹出核对指纹的确认,由用户决定接不接受。
// 对方没收到回复会接着重发,同一台设备的请求只弹一次。
func (m *Manager) acceptNearby(peer lan.PeerInfo) bool {
	m.mu.RLock()
	for _, p := range m.pending {
		if p.initiated && p.peer.ID == peer.ID {
			m.mu.RUnlock()
			return true
		}
	}
	m.mu.RUnlock()

	_, err := m.addPending(store.Device{
		ID:        peer.ID,
		Name:      peer.Name,
		Platform:  peer.Platform,
		PublicKey: peer.PublicKey,
	}, true, peer.Addrs)
	return err == nil
}

// ErrBadPeerID 表示对方的 device_id 与公钥对不上:有人在转发途中改了它。
var ErrBadPeerID = errors.New("对方的设备 ID 与公钥不匹配")

func (m *Manager) addPending(peer store.Device, initiated bool, addrs []string) (string, error) {
	// 局域网里「搜索附近设备」的配对:两边都是配对
	return m.addPendingFor(peer, initiated, addrs, lan.IntentDevice, lan.IntentDevice, nil)
}

// addPendingFor 记下一个待用户确认的配对或加好友。peerIntent 为空表示还不知道对方的用途
// (经服务器兑换的),之后用 PairIntent 信令交换。
func (m *Manager) addPendingFor(peer store.Device, initiated bool, addrs []string, intent, peerIntent string, peerCard *pb.FriendCard) (string, error) {
	// 校验对端 ID 确由其公钥派生,挡住服务器伪造的 device_id
	if !deviceid.Valid(peer.ID, peer.PublicKey) {
		m.log.Warn("拒绝配对:device_id 与公钥不匹配", "device", peer.ID)
		return "", ErrBadPeerID
	}
	if peer.ID == m.identity.DeviceID {
		return "", ErrBadPeerID
	}
	m.mu.RLock()
	role := m.roleLocked(peer.ID)
	m.mu.RUnlock()
	if intent == lan.IntentFriend && role == RoleSelf {
		return "", ErrAlreadyPaired
	}

	session := randomToken()
	p := &pendingPair{
		session:     session,
		peer:        peer,
		expiresAt:   time.Now().Add(pendingTTL),
		initiated:   initiated,
		addrs:       addrs,
		intent:      intent,
		peerIntent:  peerIntent,
		peerCard:    peerCard,
		intentKnown: make(chan struct{}),
	}
	m.mu.Lock()
	m.pending[session] = p
	m.mu.Unlock()

	m.log.Info("等待用户核对配对指纹",
		"peer", peer.Name, "device", peer.ID, "intent", intent,
		"fingerprint", deviceid.Fingerprint(peer.PublicKey))
	m.lan.PeersChanged()

	if peerIntent == "" {
		go m.exchangeIntent(session)
	} else {
		m.evaluateIntent(p)
	}
	// 配对的发起方侧是被动收到的,主动推给 UI 让它弹出确认;加好友等两边用途一致后再推(evaluateIntent)
	if initiated && intent == lan.IntentDevice {
		m.notify(m.toProto(peer, false, session))
	}
	return session, nil
}

// ─────────────────────── 对外 API ───────────────────────

var (
	// ErrNoChannel 表示局域网发现已关闭,也没连上服务器,没法配对
	ErrNoChannel      = errors.New("局域网发现已关闭,也没有连上服务器")
	ErrSessionUnknown = errors.New("配对会话不存在或已过期")
	// ErrCodeRejected 是服务器拒绝了配对码:码不存在或已过期,服务器不区分这两种
	ErrCodeRejected = errors.New("配对码不对或已失效")
	ErrNotPaired    = errors.New("没有与这台设备配对")
)

// CreatePairingCode 生成配对码,返回码、有效期和本机的局域网地址。
//
// 连着服务器时用服务器签发的码,同一个码也在局域网里开放,两边谁先用掉算谁的;
// 没连服务器时在本机生成,只在局域网里开放。
func (m *Manager) CreatePairingCode(ctx context.Context) (string, time.Time, []string, error) {
	return m.createCode(ctx, lan.IntentDevice)
}

func (m *Manager) createCode(ctx context.Context, intent string) (string, time.Time, []string, error) {
	lanOn := m.lan.Running()
	var code string
	var expires time.Time
	if m.client.Connected() {
		var err error
		code, expires, err = m.serverPairingCode(ctx)
		if err != nil && !lanOn {
			return "", time.Time{}, nil, err
		}
		if err != nil {
			m.log.Warn("服务器没给出配对码,改为只在局域网里配对", "err", err)
		}
	}
	if code == "" {
		if !lanOn {
			return "", time.Time{}, nil, ErrNoChannel
		}
		var err error
		if code, err = pairingcode.Generate(); err != nil {
			return "", time.Time{}, nil, err
		}
		expires = time.Now().Add(pairingcode.TTL)
	}

	m.mu.Lock()
	m.active = &activeCode{code: code, expires: expires, intent: intent}
	m.mu.Unlock()
	if lanOn {
		var card *pb.FriendCard
		if intent == lan.IntentFriend {
			card = m.selfCard()
		}
		m.lan.OpenPairingFor(code, expires, intent, card)
	}
	return code, expires, m.lan.DisplayAddrs(), nil
}

// serverPairingCode 请服务器签发配对码。服务器异步返回,这里等待结果。
func (m *Manager) serverPairingCode(ctx context.Context) (string, time.Time, error) {
	ch := make(chan pairingCode, 1)
	m.mu.Lock()
	m.codeWaiters = append(m.codeWaiters, ch)
	m.mu.Unlock()

	if err := m.client.CreatePairingCode(ctx); err != nil {
		return "", time.Time{}, err
	}

	select {
	case got := <-ch:
		return got.code, got.expiresAt, got.err
	case <-ctx.Done():
		return "", time.Time{}, ctx.Err()
	case <-time.After(10 * time.Second):
		return "", time.Time{}, errors.New("等待配对码超时")
	}
}

// RedeemPairingCode 兑换配对码,返回待用户核对的对端信息与会话 ID。
// 此时尚未建立互信——必须再调 ConfirmPairing。
//
// 先在局域网里找(address 是用户输入的对方地址,不在同一网段时用),
// 找不到且连着服务器时再去服务器上兑换。
func (m *Manager) RedeemPairingCode(ctx context.Context, code, address string) (*pb.Device, string, error) {
	code, friend := splitCode(code)
	if friend {
		return nil, "", ErrIsFriendCode
	}
	var extra []netip.AddrPort
	if address != "" {
		aps, err := lan.ResolveAddress(ctx, address)
		if err != nil {
			return nil, "", err
		}
		extra = aps
	}

	lanErr := lan.ErrDisabled
	if m.lan.Running() {
		wait := 3 * time.Second
		if len(extra) > 0 {
			wait = 5 * time.Second
		}
		lctx, cancel := context.WithTimeout(ctx, wait)
		peer, err := m.lan.Pair(lctx, code, extra)
		cancel()
		if err == nil {
			dev := store.Device{ID: peer.ID, Name: peer.Name, Platform: peer.Platform, PublicKey: peer.PublicKey}
			session, err := m.addPending(dev, false, peer.Addrs)
			if err != nil {
				return nil, "", err
			}
			return m.toProto(dev, false, session), session, nil
		}
		if errors.Is(err, lan.ErrIsFriendCode) {
			return nil, "", ErrIsFriendCode
		}
		lanErr = err
	}

	if m.client.Connected() {
		dev, session, err := m.redeemViaServer(ctx, code)
		// 服务器也没这个码时,局域网里那台的明确拒绝(码不对、已失效)更有用
		if err != nil && (errors.Is(lanErr, lan.ErrWrongCode) || errors.Is(lanErr, lan.ErrTooManyAttempts) ||
			errors.Is(lanErr, lan.ErrCodeClosed)) {
			return nil, "", lanErr
		}
		return dev, session, err
	}
	if errors.Is(lanErr, lan.ErrDisabled) {
		return nil, "", ErrNoChannel
	}
	return nil, "", lanErr
}

func (m *Manager) redeemViaServer(ctx context.Context, code string) (*pb.Device, string, error) {
	session, err := m.redeemViaServerFor(ctx, code, lan.IntentDevice)
	if err != nil {
		return nil, "", err
	}
	m.mu.RLock()
	p := m.pending[session]
	m.mu.RUnlock()
	if p == nil {
		return nil, "", ErrSessionUnknown
	}
	return m.toProto(p.peer, false, session), session, nil
}

// redeemViaServerFor 经服务器兑换配对码或好友码,返回待确认的会话。
// 服务器不知道用途,之后两边用签名的 PairIntent 信令互相说明(见 exchangeIntent)
func (m *Manager) redeemViaServerFor(ctx context.Context, code, intent string) (string, error) {
	ch := make(chan redeemResult, 1)
	m.mu.Lock()
	m.redeemWaiters = append(m.redeemWaiters, ch)
	m.mu.Unlock()
	drop := func() {
		m.mu.Lock()
		for i, w := range m.redeemWaiters {
			if w == ch {
				m.redeemWaiters = append(m.redeemWaiters[:i], m.redeemWaiters[i+1:]...)
				break
			}
		}
		m.mu.Unlock()
	}

	if err := m.client.RedeemPairingCode(ctx, code); err != nil {
		drop()
		return "", err
	}
	select {
	case r := <-ch:
		if r.err != nil {
			return "", r.err
		}
		dev := store.Device{
			ID:        r.ev.GetPeerDeviceId(),
			Name:      r.ev.GetPeerDeviceName(),
			Platform:  r.ev.GetPeerPlatform(),
			PublicKey: r.ev.GetPeerPublicKey(),
		}
		return m.addPendingFor(dev, false, nil, intent, "", nil)
	case <-ctx.Done():
		drop()
		return "", ctx.Err()
	case <-time.After(10 * time.Second):
		drop()
		return "", ErrCodeRejected
	}
}

// ShowNearby 在「搜索附近设备」窗口打开期间公开本机,窗口关掉时调用返回的函数。见 lan.Transport.ShowNearby。
func (m *Manager) ShowNearby() (hide func()) { return m.lan.ShowNearby() }

// Nearby 返回附近同样打开了「搜索附近设备」窗口的设备。
func (m *Manager) Nearby() []*pb.NearbyDevice {
	list := m.lan.Nearby()
	m.mu.RLock()
	defer m.mu.RUnlock()
	out := make([]*pb.NearbyDevice, 0, len(list))
	for _, n := range list {
		_, paired := m.known[n.PeerID]
		out = append(out, &pb.NearbyDevice{
			Id:       n.ID,
			Name:     n.Name,
			Platform: n.Platform,
			Paired:   n.PeerID != "" && paired,
		})
	}
	return out
}

// PairNearby 向附近的一台设备发起配对,返回待用户核对的对端信息与会话 ID。
// 与 RedeemPairingCode 一样,此时尚未建立互信——必须再调 ConfirmPairing。
func (m *Manager) PairNearby(ctx context.Context, id string) (*pb.Device, string, error) {
	if !m.lan.Running() {
		return nil, "", ErrNoChannel
	}
	lctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	peer, err := m.lan.PairNearby(lctx, id)
	cancel()
	if err != nil {
		return nil, "", err
	}
	dev := store.Device{ID: peer.ID, Name: peer.Name, Platform: peer.Platform, PublicKey: peer.PublicKey}
	session, err := m.addPending(dev, false, peer.Addrs)
	if err != nil {
		return nil, "", err
	}
	return m.toProto(dev, false, session), session, nil
}

// ConfirmPairing 在用户核对指纹后落库,正式建立互信。
func (m *Manager) ConfirmPairing(ctx context.Context, session string, accept bool) error {
	// 经服务器兑换的还不知道对方的用途时,等它一会儿:对方开放的若是好友码,不能配成自己的设备。
	// 旧版本从不说明用途,等不到就当作配对
	m.mu.RLock()
	p, ok := m.pending[session]
	m.mu.RUnlock()
	if ok && accept && p.intent == lan.IntentDevice {
		select {
		case <-p.intentKnown:
		case <-time.After(intentConfirmWait):
		case <-ctx.Done():
			return ctx.Err()
		}
	}

	m.mu.Lock()
	p, ok = m.pending[session]
	if ok && p.intent == lan.IntentFriend {
		ok = false
	}
	if ok {
		delete(m.pending, session)
	}
	mismatch := m.mismatched[session]
	m.mu.Unlock()

	if !ok {
		if mismatch != nil {
			return mismatch
		}
		return ErrSessionUnknown
	}
	if !accept {
		m.log.Info("用户拒绝配对", "peer", p.peer.Name)
		m.mu.Lock()
		delete(m.stashed, p.peer.ID)
		m.mu.Unlock()
		return nil
	}

	p.peer.PairedAt = time.Now()
	if err := m.store.PutDevice(p.peer); err != nil {
		return fmt.Errorf("保存设备: %w", err)
	}

	m.mu.Lock()
	m.known[p.peer.ID] = p.peer
	m.mu.Unlock()

	m.log.Info("配对成功", "peer", p.peer.Name, "device", p.peer.ID)

	// 配对时对方所在的地址记进地址簿(设备已落库,外键才满足),然后马上去局域网里找它
	if len(p.addrs) > 0 {
		m.lan.Remember(p.peer.ID, p.addrs)
	}
	m.lan.PeersChanged()

	// 让服务器知道我们现在关心这个设备的在线状态
	if m.client.Connected() {
		if err := m.client.RefreshPaired(ctx); err != nil {
			m.log.Warn("刷新关注列表失败", "err", err)
		}
	}
	if d, ok := m.device(p.peer.ID); ok {
		m.notify(d)
	}

	// 先重放对方在本端确认前发来的信令,这样握手能一次成功,
	// 不必等连接超时后再重来一轮。
	m.replaySignals(p.peer.ID)

	// 对方没抢先发起时,由本端补发一次。
	go func() {
		connectCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
		defer cancel()
		if m.p2p.State(p.peer.ID) != p2p.StateOffline {
			return
		}
		if err := m.p2p.Connect(connectCtx, p.peer.ID); err != nil {
			m.log.Debug("配对后建立连接失败,将由巡检重试", "err", err)
		}
	}()
	return nil
}

func (m *Manager) Unpair(ctx context.Context, deviceID string) error {
	if err := m.store.DeleteDevice(deviceID); err != nil {
		return err
	}
	m.mu.Lock()
	delete(m.known, deviceID)
	delete(m.serverOnline, deviceID)
	delete(m.conn, deviceID)
	delete(m.features, deviceID)
	m.mu.Unlock()

	// 已经不再互信,连接也不该留着
	m.p2p.Disconnect(deviceID)
	m.lan.Forget(deviceID)
	if m.client.Connected() {
		if err := m.client.RefreshPaired(ctx); err != nil {
			m.log.Warn("刷新关注列表失败", "err", err)
		}
	}
	m.log.Info("已解除配对", "device", deviceID)
	m.notifyStatus()
	return nil
}

// reconnectWait 是「重新连接」最多等多久再报告结果。换直连的 ICE 重启通常几秒内就有结果
const reconnectWait = 15 * time.Second

// Reconnect 是设备菜单里的「重新连接」。已是直连时什么也不做;不在线的马上去找它
// (局域网里打招呼、信令服务器断着的马上重连),找到就发起连接;走中转的马上再试一次直连,
// 打不通照旧走中转。直连了就立即返回,否则最多等 reconnectWait,返回那时的连接状态。
func (m *Manager) Reconnect(ctx context.Context, deviceID string) (pb.ConnectionKind, error) {
	role := m.Role(deviceID)
	if role == "" {
		return pb.ConnectionKind_CONNECTION_KIND_UNSPECIFIED, ErrNotPaired
	}
	if role != RoleSelf {
		m.touch(deviceID)
	}
	if m.p2p.State(deviceID) == p2p.StateDirect {
		return pb.ConnectionKind_CONNECTION_KIND_DIRECT, nil
	}
	m.log.Info("用户要求重新连接", "device", deviceID, "state", m.p2p.State(deviceID))
	m.client.Redial()
	m.lan.PeersChanged()

	deadline := time.Now().Add(reconnectWait)
	asked := false
	for {
		st := m.p2p.State(deviceID)
		if st == p2p.StateDirect {
			return pb.ConnectionKind_CONNECTION_KIND_DIRECT, nil
		}
		if !asked && m.IsOnline(deviceID) {
			asked = true
			if err := m.p2p.RetryDirect(ctx, deviceID); err != nil {
				m.log.Debug("重新连接没有发起", "device", deviceID, "err", err)
			}
		}
		if time.Now().After(deadline) {
			break
		}
		select {
		case <-ctx.Done():
			return st.Proto(), nil
		case <-time.After(250 * time.Millisecond):
		}
	}
	if !m.IsOnline(deviceID) {
		return pb.ConnectionKind_CONNECTION_KIND_OFFLINE, nil
	}
	return m.p2p.State(deviceID).Proto(), nil
}

// SetDeviceAddress 记下用户手动输入的某台设备的地址,并立即去那里找它。
func (m *Manager) SetDeviceAddress(ctx context.Context, deviceID, address string) error {
	m.mu.RLock()
	_, ok := m.known[deviceID]
	m.mu.RUnlock()
	if !ok {
		return ErrNotPaired
	}
	if !m.lan.Running() {
		return lan.ErrDisabled
	}
	return m.lan.SetPeerAddr(ctx, deviceID, address)
}

// LANInfo 返回局域网直连的诊断信息。
func (m *Manager) LANInfo() *pb.LanInfo {
	info := m.lan.Info()
	out := &pb.LanInfo{
		Enabled:        info.Running,
		Port:           int32(info.Port),
		LocalAddresses: info.LocalAddrs,
		Discovered:     int32(info.Discovered),
		Blocked:        info.Blocked,
	}
	m.mu.RLock()
	defer m.mu.RUnlock()
	for _, p := range info.Peers {
		lp := &pb.LanPeer{
			DeviceId:       p.ID,
			DeviceName:     m.known[p.ID].Name,
			Reachable:      p.Reachable,
			Address:        p.Addr,
			KnownAddresses: p.Known,
		}
		if !p.LastSeen.IsZero() {
			lp.LastSeenUnix = p.LastSeen.Unix()
		}
		out.Peers = append(out.Peers, lp)
	}
	return out
}

// Devices 返回本机与所有已配对设备。
func (m *Manager) Devices() (*pb.Device, []*pb.Device) {
	cfg := m.loadConfig()
	self := &pb.Device{
		Id:                   m.identity.DeviceID,
		Name:                 cfg.DeviceName,
		Platform:             runtime.GOOS,
		Online:               m.client.Connected() || m.lan.Running(),
		PublicKeyFingerprint: m.identity.Fingerprint(),
	}

	m.mu.RLock()
	defer m.mu.RUnlock()
	peers := make([]*pb.Device, 0, len(m.known))
	for _, d := range m.known {
		peers = append(peers, m.toProtoLocked(d, m.isOnlineLocked(d.ID), ""))
	}
	return self, peers
}

// Signal 向对端发送信令。M2 的 WebRTC 层用它交换 SDP 与 candidate。
func (m *Manager) Signal(ctx context.Context, to string, msg *pb.SignalMessage) error {
	return m.sendSignal(ctx, to, msg)
}

func (m *Manager) IsOnline(deviceID string) bool {
	m.mu.RLock()
	defer m.mu.RUnlock()
	return m.isOnlineLocked(deviceID)
}

// isOnlineLocked:服务器说在线、局域网里找得到、或者 P2P 已经连着,都算在线。
func (m *Manager) isOnlineLocked(deviceID string) bool {
	return m.serverOnline[deviceID] || m.lan.Reachable(deviceID) || connected(m.conn[deviceID])
}

// pairedIDs 返回所有已配对设备,供局域网通道去找它们。
func (m *Manager) pairedIDs() []string {
	m.mu.RLock()
	defer m.mu.RUnlock()
	ids := make([]string, 0, len(m.known))
	for id := range m.known {
		ids = append(ids, id)
	}
	return ids
}

// ─────────────────────── 内部辅助 ───────────────────────

func (m *Manager) device(deviceID string) (*pb.Device, bool) {
	m.mu.RLock()
	defer m.mu.RUnlock()
	d, ok := m.known[deviceID]
	if !ok {
		return nil, false
	}
	return m.toProtoLocked(d, m.isOnlineLocked(deviceID), ""), true
}

func (m *Manager) toProto(d store.Device, online bool, session string) *pb.Device {
	m.mu.RLock()
	defer m.mu.RUnlock()
	return m.toProtoLocked(d, online, session)
}

func (m *Manager) toProtoLocked(d store.Device, online bool, session string) *pb.Device {
	conn := pb.ConnectionKind_CONNECTION_KIND_OFFLINE
	if online {
		// 已有 P2P 通道时显示具体是直连还是中转,便于用户排查网络问题
		conn = m.conn[d.ID].Proto()
	}
	f := m.features[d.ID]
	_, declared := m.features[d.ID]
	return &pb.Device{
		Id:                   d.ID,
		Name:                 d.Name,
		Platform:             d.Platform,
		Online:               online,
		Connection:           conn,
		PublicKeyFingerprint: deviceid.Fingerprint(d.PublicKey),
		PairedAtUnix:         d.PairedAt.Unix(),
		PairingSession:       session,
		ReceivesFiles:        ReceivesSendFiles(f, d.Platform),
		ReceiveDisabled:      f[FeatureSendFilesOff],
		LanReachable:         online && m.lan.Reachable(d.ID),
		FeaturesKnown:        declared || m.legacy[d.ID],
		AppVersion:           m.peerVersion[d.ID],
	}
}

func (m *Manager) notify(d *pb.Device) {
	if m.onDeviceChanged != nil && d != nil {
		m.onDeviceChanged(d)
	}
}

func (m *Manager) notifyAll() {
	_, peers := m.Devices()
	for _, d := range peers {
		m.notify(d)
	}
}

func (m *Manager) notifyStatus() {
	if m.onStatusChanged != nil {
		m.onStatusChanged()
	}
}

// gcPending 清理用户迟迟未确认的配对会话。
func (m *Manager) gcPending(ctx context.Context) {
	t := time.NewTicker(time.Minute)
	defer t.Stop()
	for {
		select {
		case <-ctx.Done():
			return
		case now := <-t.C:
			m.mu.Lock()
			for k, p := range m.pending {
				if now.After(p.expiresAt) {
					delete(m.pending, k)
				}
			}
			if len(m.mismatched) > 64 {
				m.mismatched = make(map[string]error)
			}
			m.mu.Unlock()
		}
	}
}

func randomToken() string {
	b := make([]byte, 16)
	if _, err := rand.Read(b); err != nil {
		// 密码学随机源不可用时没有安全的降级方案
		panic(fmt.Sprintf("生成会话 ID 失败: %v", err))
	}
	return hex.EncodeToString(b)
}