Easytier/easytier/docs/credential_peer.md

临时凭据（Credential）系统实现计划

Context

EasyTier 的 secure mode 已实现 Noise XX 握手 + X25519 静态公钥认证。当前节点通过 network_secret 双向确认身份。用户需要一种"临时凭据"机制：

• 管理节点（任何持有 network_secret 的节点）可为当前网络生成凭据
• 新节点可使用凭据代替 network_secret 加入网络
• 管理节点可撤销凭据
• 撤销后，使用该凭据接入的节点被全网踢出

核心设计：凭据 = X25519 密钥对。完全复用现有 Noise Noise_XX_25519_ChaChaPoly_SHA256 握手流程，无需修改握手消息格式。通过 OSPF 路由同步传播可信公钥列表，撤销时全网自然断开。

整体架构

凭据 = X25519 密钥对
  - 管理节点生成密钥对，将公钥加入可信列表
  - 临时节点持有私钥，用作 Noise static key
  - 全网通过 OSPF 路由同步可信公钥列表

管理节点 (持有 network_secret):
  1. generate_credential() → 生成 X25519 密钥对
  2. 公钥记入 trusted_credential_pubkeys → 随 RoutePeerInfo 通过 OSPF 传播
  3. revoke → 从 trusted 列表移除 → OSPF 同步 → 全网感知

临时节点 (持有凭据私钥):
  1. 使用凭据私钥作为 SecureModeConfig.local_private_key
  2. Noise 握手完全走现有流程（XX 模式交换 static pubkey）
  3. 不持有 network_secret，secret_proof 验证会失败，但公钥在可信列表中即可
  4. RoutePeerInfo.noise_static_pubkey 自然携带凭据公钥

校验逻辑（每个节点在路由同步时执行）:
  1. 从全网 RoutePeerInfo 中收集管理节点的 trusted_credential_pubkeys（取并集）
     **安全约束: 仅信任 secure_auth_level=NetworkSecretConfirmed 的节点发布的列表**
     临时节点（CredentialAuthenticated）发布的 trusted_credential_pubkeys 必须被忽略
  2. 对每个 peer，如果其 secure_auth_level < NetworkSecretConfirmed:
     - 检查其 noise_static_pubkey 是否在可信公钥集合中
     - 不在 → 从路由表移除 → 断开连接

详细设计

Step 1: Protobuf 定义

文件: easytier/src/proto/peer_rpc.proto

在 RoutePeerInfo 新增字段（利用已有 noise_static_pubkey 字段 #18）:

message TrustedCredentialPubkey {
  bytes pubkey = 1;              // X25519 公钥 (32 bytes)
  repeated string groups = 2;   // 该凭据所属的 ACL group（管理节点声明，无需 proof）
  bool allow_relay = 3;         // 是否允许该临时节点提供 peer relay 能力
  int64 expiry_unix = 4;          // 必选：过期时间（Unix timestamp），过期后自动失效
  repeated string allowed_proxy_cidrs = 5; // 允许该临时节点声明的 proxy_cidrs 范围
}

message RoutePeerInfo {
  // ... existing fields 1-18 ...
  // 管理节点发布的可信凭据公钥列表（含 group 关联）
  repeated TrustedCredentialPubkey trusted_credential_pubkeys = 19;
}

临时节点无需新字段——其 noise_static_pubkey（字段 18）已经在 OSPF 中传播，只需在校验端判断该公钥是否在可信列表中。

新增 SecureAuthLevel 枚举值:

enum SecureAuthLevel {
  None = 0;
  EncryptedUnauthenticated = 1;
  SharedNodePubkeyVerified = 2;
  NetworkSecretConfirmed = 3;
  CredentialAuthenticated = 4;  // 新增：凭据公钥已验证
}

文件: easytier/src/proto/api_instance.proto

新增凭据管理 RPC:

message GenerateCredentialRequest {
  repeated string groups = 1;   // 可选: 凭据关联的 ACL group
  bool allow_relay = 2;         // 可选: 是否允许该临时节点提供 peer relay
  repeated string allowed_proxy_cidrs = 3; // 可选: 限制可声明的 proxy_cidrs
  int64 ttl_seconds = 4;        // 必选: 凭据有效期（秒）
}
message GenerateCredentialResponse {
  string credential_id = 1;       // 公钥的 base64
  string credential_secret = 2;   // 私钥的 base64
}
message RevokeCredentialRequest { string credential_id = 1; }
message RevokeCredentialResponse { bool success = 1; }
message ListCredentialsRequest {}
message CredentialInfo {
  string credential_id = 1;       // 公钥 base64
  google.protobuf.Timestamp created_at = 2;
}
message ListCredentialsResponse { repeated CredentialInfo credentials = 1; }

service CredentialManageRpc {
  rpc GenerateCredential(GenerateCredentialRequest) returns (GenerateCredentialResponse);
  rpc RevokeCredential(RevokeCredentialRequest) returns (RevokeCredentialResponse);
  rpc ListCredentials(ListCredentialsRequest) returns (ListCredentialsResponse);
}

Step 2: 凭据管理模块

新文件: easytier/src/peers/credential_manager.rs

use x25519_dalek::{StaticSecret, PublicKey};

pub struct CredentialManager {
    // 本节点管理的可信凭据
    credentials: DashMap<String, CredentialEntry>,  // credential_id (pubkey base64) -> entry
    storage_path: Option<PathBuf>,                  // 可选: 凭据 JSON 文件路径
}

struct CredentialEntry {
    pubkey_bytes: [u8; 32],
    groups: Vec<String>,           // 关联的 ACL group（管理节点声明）
    allow_relay: bool,             // 是否允许 relay
    allowed_proxy_cidrs: Vec<String>, // 允许声明的 proxy_cidrs 范围
    expiry: SystemTime,             // 过期时间（必选）
    created_at: SystemTime,
}

impl CredentialManager {
    /// 生成新凭据（含 group 关联）
    /// 返回 (credential_id=公钥base64, credential_secret=私钥base64)
    pub fn generate_credential(&self, groups: Vec<String>, allow_relay: bool, expiry: SystemTime) -> (String, String) {
        let private = StaticSecret::random_from_rng(OsRng);
        let public = PublicKey::from(&private);
        let id = BASE64_STANDARD.encode(public.as_bytes());
        let secret = BASE64_STANDARD.encode(private.as_bytes());
        self.credentials.insert(id.clone(), CredentialEntry {
            pubkey_bytes: *public.as_bytes(),
            groups,
            allow_relay,
            expiry,  // 由调用方传入
            created_at: SystemTime::now(),
        });
        self.save_to_disk();  // 持久化
        (id, secret)
    }

    /// 撤销凭据
    pub fn revoke_credential(&self, credential_id: &str) -> bool;

    /// 获取可信凭据列表（用于 RoutePeerInfo.trusted_credential_pubkeys）
    pub fn get_trusted_pubkeys(&self) -> Vec<TrustedCredentialPubkey>;

    /// 列出所有凭据
    pub fn list_credentials(&self) -> Vec<CredentialInfo>;
}

Step 3: Noise 握手适配（最小改动）

文件: easytier/src/peers/peer_conn.rs

临时节点的握手流程完全不需要修改，因为:

• 临时节点配置 SecureModeConfig { enabled: true, local_private_key: 凭据私钥, local_public_key: 凭据公钥 }
• get_keypair() (line 434) 自然返回凭据密钥对
• Noise XX 握手正常交换 static pubkey
• 唯一区别：secret_proof_32 验证会失败（临时节点没有 network_secret）

需要修改 do_noise_handshake_as_server() (line 934):

• 当前行为: secret_proof 验证失败 → 返回错误断开连接 (line 1059)
• 修改为: secret_proof 验证失败时，不立即断开，而是将 secure_auth_level 保持为 EncryptedUnauthenticated
• 后续由 OSPF 路由同步阶段决定该 peer 是否可信（公钥是否在 trusted 列表中）

同样修改 do_noise_handshake_as_client() (line 680):

• 当临时节点连接管理节点时，secret_proof 验证失败不应报错
• 临时节点可以通过 pinned_remote_pubkey 或不验证来处理

NoiseHandshakeResult 新增:

// 标记此连接使用了凭据而非 network_secret
is_credential_conn: bool,

Step 4: RoutePeerInfo 传播凭据信息

文件: easytier/src/peers/peer_ospf_route.rs

修改 RoutePeerInfo::new_updated_self() (line 164):

• 管理节点（持有 network_secret）: 从 CredentialManager.get_trusted_pubkeys() 获取列表，填入 trusted_credential_pubkeys
• 临时节点: 不填写 trusted_credential_pubkeys（该字段留空），即使收到其他管理节点传播的列表也不转发
  • 实现方式: 在 new_updated_self() 中检查节点身份，临时节点跳过 trusted_credential_pubkeys 填充
• 临时节点: 无需额外操作，noise_static_pubkey 已自然包含凭据公钥

Step 5: 全网校验与自动踢出（核心逻辑）

文件: easytier/src/peers/peer_ospf_route.rs

在 SyncedRouteInfo 中新增:

// 从全网管理节点汇总的可信凭据公钥集合
trusted_credential_pubkeys: DashSet<Vec<u8>>,  // pubkey bytes

新增校验方法（类似 verify_and_update_group_trusts line 743）:

fn verify_credential_peers(&self, peer_infos: &[RoutePeerInfo]) {
    // 1. 收集管理节点的 trusted_credential_pubkeys（取并集）
    //    **安全约束: 仅信任 secret_digest 与本网络匹配的节点（即持有 network_secret 的管理节点）**
    //    临时节点的 trusted_credential_pubkeys 直接忽略，防止恶意临时节点自我授权
    let mut all_trusted = HashSet::new();
    for info in peer_infos {
        if self.is_peer_secret_verified(info.peer_id) {
            // 该 peer 通过了 network_secret 双向确认，是合法管理节点
            for tc in &info.trusted_credential_pubkeys {
                all_trusted.insert(tc.pubkey.clone());
            }
        }
        // else: 该 peer 未通过 network_secret 确认（含临时节点），忽略其 trusted 列表
    }
    self.trusted_credential_pubkeys = all_trusted;

    // 2. 检查所有 peer 的凭据状态
    for info in peer_infos {
        if !self.is_peer_secret_verified(info.peer_id)
           && !info.noise_static_pubkey.is_empty()
        {
            if !self.trusted_credential_pubkeys.contains(&info.noise_static_pubkey) {
                // 该 peer 既不持有 network_secret，其公钥也不在可信列表中
                // → 标记为不可信，后续从路由表移除
                self.mark_peer_untrusted(info.peer_id);
            }
        }
    }
}

在 do_sync_route_info() (line 2614) 中调用此校验。

在路由表构建中（update_route_table_and_cached_local_conn_bitmap()）:

• 不可信 peer 不加入路由图
• 已连接的不可信 peer 调用 PeerMap::close_peer() 断开

判断 peer 是否持有 network_secret: 利用现有 secret_digest 字段。管理节点的 RoutePeerInfo 中 secret_digest 与本节点匹配，说明双方持有相同的 network_secret。

Step 6: GlobalCtx / Config 集成

文件: easytier/src/common/global_ctx.rs

在 GlobalCtx 新增:

credential_manager: Arc<CredentialManager>,  // 所有节点都持有，管理节点用于生成/撤销

文件: easytier/src/common/global_ctx.rs - GlobalCtxEvent

新增:

CredentialChanged,  // 触发 OSPF 立即同步

文件: easytier/src/common/config.rs

临时节点的配置方式: 直接使用凭据私钥作为 SecureModeConfig.local_private_key。 可在 TomlConfigLoader 中新增便捷字段或 CLI 参数:

• --credential <私钥base64>: 临时节点使用凭据私钥加入网络
• --credential-file <path>: 管理节点指定凭据存储 JSON 文件路径

Step 7: RPC 服务 + CLI

文件: easytier/src/peers/rpc_service.rs

实现 CredentialManageRpc，参考 PeerManagerRpcService 模式。

CLI (easytier-cli):

easytier-cli credential generate
  输出: credential_id=<公钥base64>  credential_secret=<私钥base64>

easytier-cli credential revoke <credential_id>
easytier-cli credential list

临时节点启动:

# 方式1: 直接传入凭据私钥
easytier-core --network-name test \
  --secure-mode \
  --credential <私钥base64> \
  --peers tcp://管理节点:11010

# 内部实现: 将凭据私钥设为 SecureModeConfig.local_private_key

Step 8: 连接时验证（握手后快速拒绝，必选）

在 do_noise_handshake_as_server() 完成后，必须进行快速检查:

• 如果对端 secret_proof 验证失败（非管理节点），且对端 noise_static_pubkey 不在本节点已知的 trusted_credential_pubkeys 中
• 立即断开连接

这是必选的安全措施（非可选优化）。因为 Step 3 放宽了 secret_proof 失败的处理，如果不做快速拒绝，任何随机节点都能与管理节点建立加密连接并持有，浪费资源。

// 在 handshake 完成后
if !secret_proof_verified {
    let remote_pubkey = handshake_result.remote_static_pubkey;
    if !self.global_ctx.credential_manager.is_pubkey_trusted(&remote_pubkey) {
        return Err(Error::AuthError("unknown credential".to_string()));
    }
    // 公钥在 trusted 列表中 → 允许连接，标记为 CredentialAuthenticated
    handshake_result.secure_auth_level = SecureAuthLevel::CredentialAuthenticated;
}

关键文件清单

文件	修改内容
easytier/src/proto/peer_rpc.proto	RoutePeerInfo 加 trusted_credential_pubkeys; SecureAuthLevel 加 CredentialAuthenticated
easytier/src/proto/api_instance.proto	新增 CredentialManageRpc 服务及消息定义
easytier/src/peers/credential_manager.rs	新文件 — 凭据管理器（密钥对生成/撤销/列表）
easytier/src/peers/mod.rs	导出 credential_manager
easytier/src/peers/peer_ospf_route.rs	new_updated_self() 填 trusted_pubkeys; 新增 verify_credential_peers(); 路由表过滤
easytier/src/peers/peer_conn.rs	do_noise_handshake_as_server() 放宽 secret_proof 失败为非致命; 可选握手阶段快速拒绝
easytier/src/peers/peer_manager.rs	集成 CredentialManager; 不可信 peer 断连逻辑
easytier/src/common/global_ctx.rs	持有 CredentialManager; 新增 CredentialChanged 事件
easytier/src/common/config.rs	新增 --credential 参数处理
easytier/src/peers/rpc_service.rs	实现 CredentialManageRpc
easytier/src/proto/common.rs	SecureModeConfig 可选: credential 模式识别

复用现有机制

现有机制	路径	复用方式
Noise XX 握手	peer_conn.rs:680,934	临时节点直接使用凭据密钥对走完整 Noise 流程
SecureModeConfig	proto/common.rs:367	临时节点的凭据私钥直接设为 local_private_key
noise_static_pubkey	RoutePeerInfo 字段 18	临时节点的凭据公钥已在 OSPF 中传播
verify_and_update_group_trusts()	peer_ospf_route.rs:743	凭据校验逻辑参考此模式
PeerMap::close_peer()	peer_map.rs:317	断开不可信 peer
OSPF 路由同步	SyncRouteInfoRequest	可信公钥列表随 RoutePeerInfo 自然传播
PeerManagerRpcService	rpc_service.rs:24	RPC 服务实现模式
GlobalCtxEvent	global_ctx.rs:32	新增事件触发同步

验证方案

1. 单元测试:

   • credential_manager.rs: 密钥对生成、撤销、列表
   • peer_conn.rs: 凭据节点 Noise 握手成功（无 network_secret）

2. 集成测试 (参考 tests/three_node.rs):

   • 3 节点: A + B (管理节点, network_secret) + C (临时节点, credential)
   • A 生成凭据（groups=["guest"]）→ C 使用凭据连接 → 验证 C 加入路由表、可达
   • 验证 C 的 ACL group 为 "guest"，配置 group ACL 规则后生效
   • A 撤销凭据 → 等待 OSPF 同步 (~1-3s) → 验证 C 被 A 和 B 断开
   • C 尝试重连 → 验证握手阶段被拒

3. 手动测试:

   # A: 管理节点
   easytier-core -n test -s secret --secure-mode --listeners tcp://0.0.0.0:11010
   easytier-cli credential generate  # → credential_id + credential_secret
   
   # C: 临时节点
   easytier-core -n test --secure-mode --credential <私钥base64> --peers tcp://A:11010
   
   # 验证后撤销
   easytier-cli credential revoke <credential_id>
   # C 数秒内被踢出
   

Step 9: 临时节点 OSPF 路由限制

约束: 临时节点传播的路由信息不可信，需严格限制。

9a. 管理节点不主动发起到临时节点的 OSPF session

核心原则: OSPF maintain_sessions() 构建最小生成树时，只在管理节点之间选择 initiator，不将临时节点纳入 dst_peer_id_to_initiate。但管理节点被动接受临时节点发起的 session。

文件: easytier/src/peers/peer_ospf_route.rs

修改 maintain_sessions() (line 2485):

• 在构建 dst_peer_id_to_initiate 候选列表时，过滤掉临时节点
• 管理节点之间的 MST 不受影响

// 在 maintain_sessions() 中，构建 initiator 候选时过滤临时节点
let peers: Vec<PeerId> = peers.into_iter().filter(|peer_id| {
    // 只主动发起到管理节点的 session，不主动连临时节点
    !self.is_credential_peer(*peer_id)
}).collect();

• 临时节点自身: 在 maintain_sessions() 中只将管理节点作为 initiator 候选，跳过其他临时节点

// 临时节点侧: 只主动连管理节点
if self.is_credential_node() {
    let peers: Vec<PeerId> = peers.into_iter().filter(|peer_id| {
        !self.is_credential_peer(*peer_id)  // 只连管理节点
    }).collect();
}

session 建立方式:

• 管理节点 → 管理节点: 正常 MST initiator 选择（不变）
• 临时节点 → 管理节点: 临时节点主动发起 session，管理节点被动接受
• 临时节点 → 临时节点: 不建立（双方都过滤掉对方）
• 管理节点 → 临时节点: 不主动发起（不在 initiator 候选中）

路由信息传播: 临时节点通过其主动发起的 session 调用 sync_route_info 推送自身 RoutePeerInfo。管理节点在正常 OSPF sync 中将其代理传播给其他管理节点。管理节点也通过该 session 向临时节点推送完整路由表。

9b. 管理节点只选择性接收临时节点的路由信息

文件: easytier/src/peers/peer_ospf_route.rs

临时节点通过其主动发起的 session 调用 sync_route_info，管理节点在处理时需做过滤：

• 只接收该临时节点自己的 RoutePeerInfo（route_info.peer_id == dst_peer_id），丢弃其声称的其他 peer 的路由信息
• 对临时节点自身的 RoutePeerInfo，过滤其 proxy_cidrs：只保留在 TrustedCredentialPubkey.allowed_proxy_cidrs 范围内的网段，移除超出范围的声明
• 临时节点的 foreign_network_infos 应忽略
• 临时节点的 conn_info（连接拓扑）根据 allow_relay 标志决定（见下方）

修改 update_peer_infos() (line 461):

fn update_peer_infos(
    &self, my_peer_id, my_peer_route_id, dst_peer_id,
    peer_infos, raw_peer_infos,
) -> Result<(), Error> {
    let dst_is_credential_peer = self.is_credential_peer(dst_peer_id);

    for (idx, route_info) in peer_infos.iter().enumerate() {
        // 临时节点只允许传播自己的路由信息
        if dst_is_credential_peer && route_info.peer_id != dst_peer_id {
            tracing::debug!(
                ?dst_peer_id, peer_id=?route_info.peer_id,
                "ignoring route info from credential peer for other peer"
            );
            continue;
        }

        // 过滤临时节点的 proxy_cidrs，只保留凭据允许的范围
        if dst_is_credential_peer {
            let allowed = self.get_credential_allowed_proxy_cidrs(dst_peer_id);
            if let Some(allowed_cidrs) = allowed {
                route_info.proxy_cidrs.retain(|cidr| {
                    allowed_cidrs.iter().any(|a| cidr_is_subset(cidr, a))
                });
            }
        }
        // ... existing logic ...
    }
}

修改 do_sync_route_info() (line 2614):

// 在 do_sync_route_info 中
let from_is_credential = self.is_credential_peer(from_peer_id);
let credential_allows_relay = from_is_credential
    && self.is_credential_relay_allowed(from_peer_id);

if let Some(peer_infos) = &peer_infos {
    // update_peer_infos 内部会过滤临时节点的非自身信息
    service_impl.synced_route_info.update_peer_infos(...);
}

// 临时节点的 conn_info: 仅当 allow_relay=true 时接收
if let Some(conn_info) = &conn_info {
    if !from_is_credential || credential_allows_relay {
        service_impl.synced_route_info.update_conn_info(conn_info);
    }
}

// 临时节点的 foreign_network_infos 始终不接收
if let Some(foreign_network) = &foreign_network {
    if !from_is_credential {
        service_impl.synced_route_info.update_foreign_network(foreign_network);
    }
}

conn_info 处理:

• 临时节点的 conn_info: 根据凭据的 allow_relay 标志决定是否接收
  • allow_relay = true: 管理节点接收并传播该临时节点的 conn_info，使其参与路由图，可作为 relay 转发数据
  • allow_relay = false（默认）: 忽略 conn_info，该临时节点不参与中继（仅作为叶子节点存在于路由图中）
• 临时节点的 foreign_network_infos 始终忽略

is_credential_relay_allowed() 实现:

fn is_credential_relay_allowed(&self, peer_id: PeerId) -> bool {
    // 从全网汇总的 trusted_credential_pubkeys 中查找该 peer 的凭据
    // 检查对应 TrustedCredentialPubkey.allow_relay 标志
    let peer_info = self.peer_infos.read();
    if let Some(info) = peer_info.get(&peer_id) {
        for tc in &self.all_trusted_credentials {
            if tc.pubkey == info.noise_static_pubkey {
                return tc.allow_relay;
            }
        }
    }
    false
}

注意: 即使 allow_relay=true，临时节点仍然不能转发握手包（Step 10b 限制不变），因此不会有新节点通过 relay 临时节点接入网络。relay 能力仅用于已建立连接的 peer 之间的数据转发。

9c. 临时节点的 RoutePeerInfo 中的 trusted_credential_pubkeys 被忽略

已在 Step 5 中说明：只信任 secret_digest 匹配的管理节点发布的 trusted 列表。

判断 peer 是否为临时节点的方法

在 SyncedRouteInfo / PeerRouteServiceImpl 中新增:

fn is_credential_peer(&self, peer_id: PeerId) -> bool {
    // 方法: 检查该 peer 的 RoutePeerInfo
    // 1. 如果 peer 的 noise_static_pubkey 在 trusted_credential_pubkeys 中 → 是临时节点
    // 2. 如果 peer 通过了 network_secret 确认 (secret_digest 匹配) → 是管理节点
    // 3. 在 peer_conn 握手后，可以记录 secure_auth_level 到连接信息中
    let peer_info = self.synced_route_info.peer_infos.read();
    if let Some(info) = peer_info.get(&peer_id) {
        if !info.noise_static_pubkey.is_empty()
            && self.trusted_credential_pubkeys.contains(&info.noise_static_pubkey) {
            return true;
        }
    }
    false
}

对于直连 peer，也可以在握手阶段直接记录 secure_auth_level，用于快速判断。

Step 10: 禁止通过临时节点接入网络

约束: 不得有新节点（无论是否持有 network_secret）通过临时节点的 listener 接入网络。但允许通过管理节点中继后建立 P2P 连接。

10a. 临时节点天然无法接受新节点接入（无需额外代码）

临时节点作为 listener 时，新节点的连接会自然失败，因为：

1. 临时节点没有 network_secret，无法验证对端的 secret_proof → 无法确认对端是管理节点
2. 临时节点不发布 trusted_credential_pubkeys → 对端公钥不在可信列表中
3. 对端也无法验证临时节点的 secret_proof（临时节点没有 network_secret）

因此 不需要在 add_tunnel_as_server() 中添加显式拦截逻辑。已有的 Noise 握手 + 凭据校验机制已足够阻止新节点通过临时节点接入。

例外: 已知的管理节点可以连接到临时节点（如 P2P hole punch 场景），因为管理节点的公钥已通过 OSPF 同步被临时节点知晓，握手可以成功。

10b. 临时节点不转发来自未知 peer 的连接请求

文件: easytier/src/peers/peer_manager.rs

在 packet forwarding 路径 (line 718-766) 中:

• 临时节点不应转发 HandShake / NoiseHandshakeMsg* 类型的包
• 这防止新节点通过临时节点的中继接入网络

// 在 peer_recv 循环的 forward 分支中
if to_peer_id != my_peer_id {
    // 临时节点不转发握手包（阻止新节点通过临时节点接入）
    if is_credential_node && (
        hdr.packet_type == PacketType::HandShake as u8
        || hdr.packet_type == PacketType::NoiseHandshakeMsg1 as u8
        || hdr.packet_type == PacketType::NoiseHandshakeMsg2 as u8
        || hdr.packet_type == PacketType::NoiseHandshakeMsg3 as u8
    ) {
        tracing::debug!("credential node dropping forwarded handshake packet");
        continue;
    }
    // ... existing forward logic ...
}

10c. P2P 连接通过管理节点中继仍然允许

P2P hole punch 的流程:

1. 两个节点通过管理节点交换打洞信息（RPC）
2. 建立直接 P2P tunnel
3. 在 P2P tunnel 上握手

这个流程不受影响，因为:

• 打洞信息交换通过管理节点中继（RPC），不经过临时节点
• P2P tunnel 建立后的握手是直连，不通过临时节点的 listener
• is_directly_connected=false 的连接（hole punch 结果）可以被临时节点接受

设计思路: 将凭据映射为 ACL Group，复用现有的 group-based ACL 规则系统。

现有 ACL 系统已支持基于 group 的规则匹配:

• Rule.source_groups / Rule.destination_groups (acl.proto:72-73)
• PeerGroupInfo 通过 HMAC proof 验证 peer 所属 group (peer_rpc.rs:8-38)
• verify_and_update_group_trusts() 在 OSPF 同步时更新 group trust map (peer_ospf_route.rs:743)
• get_peer_groups() 返回 peer 所属的 group 列表，用于 ACL 匹配 (peer_ospf_route.rs:2287)

方案: 生成凭据时，为每个凭据创建一个隐式 ACL Group。

1. 凭据生成时: 管理节点为凭据创建一个关联的 group:

   • group_name = "credential:<credential_id>" 或用户自定义名称
   • group_secret = 由 credential_secret 派生的密钥
   • 可选：指定凭据所属的 group_name（批量管理，如 "guest", "contractor"）

2. 临时节点加入时: 临时节点使用凭据私钥连接。其 group 归属由管理节点在 TrustedCredentialPubkey.groups 中声明（无需临时节点自己提供 group proof）。验证节点在 verify_credential_peers() 中匹配公钥后，直接将声明的 groups 加入 group_trust_map。

3. ACL 规则配置: 管理员可配置基于 group 的 ACL 规则:

   # 示例配置: 限制 "guest" group 只能访问特定子网
   [[acl.acl_v1.chains]]
   name = "inbound"
   chain_type = "Inbound"
   default_action = "Allow"
   
   [[acl.acl_v1.chains.rules]]
   name = "restrict_guest"
   source_groups = ["guest"]
   destination_ips = ["10.0.0.0/24"]
   action = "Drop"
   

4. 管理节点发布 group 信息:

   • 在 RoutePeerInfo.trusted_credential_pubkeys 中传播可信公钥时，同时包含关联的 group 信息
   • 扩展 proto: （使用 Step 1 中定义的 TrustedCredentialPubkey，group 归属由管理节点声明，无需 proof 验证）
   • 替换 repeated bytes trusted_credential_pubkeys 为 repeated TrustedCredentialPubkey trusted_credential_pubkeys

5. 校验节点处理: 在 verify_credential_peers() 中:

   • 验证凭据公钥在可信列表中后
   • 直接将 TrustedCredentialPubkey.groups 中声明的 group 加入 group_trust_map / group_trust_map_cache（无需验证 group proof，因为管理节点的声明已是可信的）
   • ACL filter 在处理数据包时自动基于 group 匹配规则

API 扩展:

生成凭据时可指定 group:

message GenerateCredentialRequest {
  repeated string groups = 1;           // 可选: 为该凭据关联的 group 名称
  bool allow_relay = 2;                 // 可选: 是否允许 relay
  repeated string allowed_proxy_cidrs = 3; // 可选: 限制可声明的 proxy_cidrs
  int64 ttl_seconds = 4;               // 必选: 凭据有效期（秒）
}

CLI:

# 生成带 group 的凭据，有效期 24 小时
easytier-cli credential generate --groups guest,restricted --ttl 86400

# 生成允许 relay 的凭据，有效期 7 天
easytier-cli credential generate --groups relay-node --allow-relay --ttl 604800

# 最简用法（默认 group 名为 "credential"）
easytier-cli credential generate --ttl 3600

安全审查

已覆盖的安全性

• 端到端加密: 数据包在源端加密、目的端解密，relay 节点（含 allow_relay 的临时节点）无法看到明文
• 临时节点自我授权防护: 只信任 secret_digest 匹配的管理节点发布的 trusted_credential_pubkeys
• 临时节点路由篡改防护: 只接收临时节点自身的 RoutePeerInfo，忽略其转发的其他路由
• 临时节点网络接入防护: 临时节点天然无法接受新节点接入（无 network_secret、不发布 trusted 列表）

需要关注的安全问题

1. Step 8 握手后快速拒绝应为必选（非可选）

当前 Step 8 标记为"可选优化"，但实际上是必须的安全措施。如果不做快速拒绝：

• 任何随机节点（无 credential、无 network_secret）都能完成 Noise 握手（因为 Step 3 放宽了 secret_proof 失败）
• 在等待 OSPF 同步验证期间，该节点持有一个有效的加密连接，浪费资源
• 修改: Step 8 改为必选。握手完成后立即检查：对端 secret_proof 失败 + 公钥不在本节点已知的 trusted 列表中 → 立即断开

2. Group proof 验证机制需要明确

当前方案：临时节点在 RoutePeerInfo.groups 中携带 PeerGroupInfo（HMAC proof），管理节点在 TrustedCredentialPubkey 中传播 group_secret_hash。

问题：HMAC 验证需要原始 secret，不是 hash。验证节点如何知道 credential 的 group secret？

解决方案: TrustedCredentialPubkey.group_secret_hash 改为 group_secret_digest，使用与现有 NetworkIdentity.network_secret_digest 相同的 digest 算法。验证时：

• 管理节点在 TrustedCredentialPubkey 中包含 group_secret_digest
• 临时节点发送的 PeerGroupInfo 中包含 group_proof（HMAC）
• 验证节点无法直接验证 HMAC（没有原始 secret），但可以信任管理节点的声明：如果管理节点在 TrustedCredentialPubkey.groups 中列出了某个 group，且临时节点的公钥匹配，就直接信任该 group 归属
• 即：group 归属由管理节点在 TrustedCredentialPubkey 中声明，无需临时节点提供 proof
• 这简化了实现，且安全性不降低（管理节点已是可信源）

3. 凭据持久化

CredentialManager 当前设计为内存存储。管理节点重启后所有凭据丢失，导致使用这些凭据的临时节点被踢出。

解决方案:

• 管理节点可配置凭据存储的 JSON 文件路径（如 --credential-file /path/to/credentials.json）
• CredentialManager 启动时从该文件加载已有凭据
• 生成/撤销凭据时自动写入该文件
• 未配置文件路径时，凭据仅存内存（重启丢失）

4. 同一凭据多节点复用

同一个 credential 私钥可以被多个节点同时使用。它们有不同的 peer_id 但相同的 noise_static_pubkey。这会导致：

• 路由表中多个 RoutePeerInfo 有相同的 noise_static_pubkey
• 撤销时所有使用该凭据的节点同时被踢出（符合预期）
• 这是预期行为，但应在文档中说明

5. 临时节点 proxy_cidrs 限制

临时节点可能声明虚假的 proxy_cidrs（子网代理），导致流量黑洞。

解决方案（已纳入设计）:

• 生成凭据时通过 allowed_proxy_cidrs 字段限制该凭据可声明的网段范围
• 管理节点在 Step 9b 的 update_peer_infos() 中过滤：只保留临时节点声明的 proxy_cidrs 中属于 allowed_proxy_cidrs 子集的网段
• 未配置 allowed_proxy_cidrs 时（空列表），临时节点不允许声明任何 proxy_cidrs

6. 凭据过期时间（TTL）

凭据必须设置过期时间。过期后自动失效，等同于被撤销。

• 生成凭据时必须指定 --ttl 或 --expiry
• verify_credential_peers() 中检查 expiry_unix，过期的凭据从可信列表中移除
• 过期检查在每次路由同步时执行，无需额外定时器

优势

• 最小改动: Noise 握手消息格式不变，完全复用现有流程
• 安全性: X25519 密钥对提供强身份认证，不弱于 network_secret；端到端加密保护 relay 场景
• 自然传播: 利用 OSPF 已有基础设施，无需新 RPC
• 去中心化撤销: 任何管理节点都可撤销，全网通过路由同步感知
• ACL 复用: 凭据映射为 ACL Group，完全复用现有 group-based ACL 规则系统，无需新的 ACL 机制