跳到主要内容

协议与 API 参考

1. JetStream Streams 与 KV Buckets​

资源类型存储 / 保留策略用途
ROGUE_CHATStreamFileStorage、30d / 100k 条 / 512 MiB公开频道 (rogue.chat.*.msg、rogue.chat.*.delete)
ROGUE_GATEDStreamFileStorage、30d / 100k 条 / 512 MiB受限频道 (rogue.gated.*.msg、rogue.gated.*.delete)
ROGUE_DMStreamFileStorage、30d / 512 MiB加密的 E2EE 私信 (rogue.dm.<0x>)
ROGUE_CHANNELSKVFileStorage频道元数据 (ChannelMeta JSON)
ROGUE_PRESENCEKVMemoryStorage、30s TTL在线用户状态 (active_room、level)
ROGUE_PROFILESKVFileStorage压缩 secp256k1 公钥与 miner_level
ROGUE_BANSKVFileStorage按小写 0x 记录的永久封禁
ROGUE_MUTESKVFileStorage、最长 24h TTL全局或按房间禁言

2. Subject 命名空间​

  • rogue.auth.nonce — 访客 Request/Reply,用于获取一次性 60s 挑战。
  • rogue.in.<0x>.chat.<room> — 客户端/代理发送房间消息的入口。
  • rogue.in.<0x>.dm.<dest0x> — 客户端/代理发送 E2EE 私信的入口。
  • rogue.in.<0x>.cmd.<action> — 入口 RPC 命令 (rooms、create_room、delete_room、topic、delete_msg、mute、unmute、ban、unban、stats)。
  • rogue.chat.<room>.msg / rogue.gated.<room>.msg — 经过验证的 v=1 消息信封。
  • rogue.err.<0x> — 结构化的 Gatekeeper 拒绝事件。

3. ECIES 线格式 (DMs)​

Go (rogue-nats) 和 Rust (rogue-desktop-client) 均实现完全相同的方案:

  1. 临时 secp256k1 密钥对 (ephem_sk, ephem_pk)。
  2. 原始 ECDH X 坐标 (32 字节)。
  3. HKDF-SHA256(salt=nil, ikm=shared_x, info="rogue-dm-ecies-v1") → 32 字节 AES-256 密钥。
  4. 使用随机 12 字节 nonce 进行 AES-256-GCM 加密。

4. Gatekeeper 错误码​

错误码含义
ERR_BAD_REQUESTJSON 格式错误、无效 0x 地址或无效房间名称 (^[a-z0-9-]{2,32}$)
ERR_BANNED地址已被永久封禁
ERR_MUTED地址在全局或目标房间中被临时禁言
ERR_RATE_LIMIT超出每个地址的消息或房间创建速率限制
ERR_ROOM_NOT_FOUND目标房间不存在
ERR_ROOM_EXISTS房间名称已被占用
ERR_ROOM_LIMIT账户已达到最多 3 个活跃用户自建房间的上限
ERR_FORBIDDENMinerLevel 不足、非管理员尝试在 #announcements 发言或非房间所有者
ERR_INSUFFICIENT_BALANCE成熟余额 (latest 与 lookbackBlocks) 低于阈值
ERR_LINK_RESTRICTED发送链接需要 >= 10 ROGUE 或 MinerLevel >= 1(仅限 https://)
ERR_INVALID_CONTENT文本为空、超过 2000 字符或包含禁止的控制/ANSI 字节
ERR_RECIPIENT_PUBKEY_UNKNOWN接收方从未连接过服务器,尚未注册其 secp256k1 公钥
ERR_RPC_UNAVAILABLE配置的 Rogue Signal JSON-RPC 端点调用失败