📝 Docs: Add websocket handshake.

Author: hanbings

docs/_sidebar.md

@@ -2,8 +2,7 @@
 - [关于协议](protocol.md)
 - [通信方式 websocket / websockets](websocket.md)
   - [服务器描述包](websocket-description-server-packet.md)
-  - [桥描述包](websocket-description-bridge-packet.md)
-  - [插件描述包](websocket-description-plugin-packet.md)
+  - [扩展描述包](websocket-description-plugin-packet.md)
 - [通信方式 http / https](http.md)
 - [聊天数据结构](unimessage.md)
 - [术语表 专用术语对照表](terminology.md)

docs/readme.md

@@ -32,8 +32,7 @@ Kat Project 是对协议的实现
 - [关于协议](protocol.md)
 - [通信方式 websocket / websockets](websocket.md)
   - [服务器描述包](websocket-description-server-packet.md)
-  - [桥描述包](websocket-description-bridge-packet.md)
-  - [插件描述包](websocket-description-plugin-packet.md)
+  - [插件描述包](websocket-description-extension-packet.md)
 - [通信方式 http / https](http.md)
 - [聊天数据结构](unimessage.md)
 - [术语表 专用术语对照表](terminology.md)

docs/websocket-description-bridge-packet.md docs/websocket-description-extension-packet.md

@@ -8,19 +8,38 @@ WebSocket 是一种在单个 TCP 连接上进行**全双工通信**的协议
 
 因此协议选用 WebSocket 作为消息传递的主要协议之一
 
+## 握手与鉴权
+
+服务端需要在 `/message` 的路由下应答客户端
+
+该信道为且只为消息传输信道，文件资源传输需要使用 http
+
+客户端发起 101 http 请求升级协议到 websocket 时应携带客户端与服务端约定的**安全密钥**
+
+携带方式为 `token` 参数，如 `https://server.catkatpowered.com/message?token=1234567890`
+
+服务端对此 token 进行鉴权，若不通过则**拒绝握手**
+
+## 安全
+
+尽可能的使用带有 ssl 的 websockets 协议，特别是对于暴露在公网的服务端来说，ssl 协议能保护链路信息
+
+强烈建议客户端与服务端使用全 ssl 通信
+
 ## 数据包
 
 本协议中，通常情况下一串完整的 json 被称之为数据包
 
 通过定义数据包的键值对，可以表达大部分所需数据
 
-这里将数据包分为以下类型
+这里将数据包分为以下四个类型
 
-| 数据包类型 |                       描述                       | 相关讨论 |
-| :--------: | :----------------------------------------------: | :------: |
-| 描述数据包 |        描述服务端、IM 连接桥、插件等信息         |          |
-| 消息数据包 | 表达 IM 的消息，是其他协议中的 **事件（Event）** |          |
-| 扩展数据包 |        由 IM 桥或插件提供的独有的数据格式        |          |
+|  数据包类型  |                       描述                       | 相关讨论 |
+| :----------: | :----------------------------------------------: | :------: |
+|  描述数据包  |        描述服务端、IM 连接桥、插件等信息         |          |
+|  消息数据包  | 表达 IM 的消息，是其他协议中的 **事件（Event）** |          |
+|  凭据数据包  |   提供用于以 http 协议获取资源的凭据（Token）    |          |
+| 自定义数据包 |        由 IM 桥或插件提供的独有的数据格式        |          |
 
 此处类型是一层逻辑分类，并非实际意义上有被分配键值对属性的数据包
 
@@ -29,13 +48,5 @@ WebSocket 是一种在单个 TCP 连接上进行**全双工通信**的协议
 此数据包分类下的数据包是包含各个模块所需提供给客户端对程序自身描述的描述数据包
 
 - [服务器描述包](websocket-description-server-packet.md)
-- [桥描述包](websocket-description-bridge-packet.md)
-- [插件描述包](websocket-description-description-packet.md)
-
-## 消息数据包
-
-此数据包分类下的数据包描述与桥交互所需的信息
-
-## 扩展数据包
+- [扩展描述包](websocket-description-description-packet.md)
 
-此数据包分类下的数据包是由桥或插件提供的特有数据包格式，各个模块应在它们的文档中描述这些特有数据包