01 四档鉴权模式

01 四档鉴权模式

本节摘要:服务端是「唯一中枢」,中枢必须管好「谁能进」。OpenWork 的鉴权不是简单的「登录/未登录」,而是四档鉴权模式:无需鉴权、客户端令牌、宿主、宿主令牌。本节讲清这四档各自适用什么场景、怎么判定,为后续的权限作用域(第 02 节)打基础。

一、为什么是四档

先想清楚鉴权的复杂性。不同资源有不同的「谁能访问」要求:

• 有些资源是公开的(如健康检查),不该要令牌。
• 有些是「登录用户都能看」的(普通浏览)。
• 有些是「只有所有者能管」的(管理操作)。
• 有些是「所有者签发的令牌才能调」的(特定授权)。

如果只有「要/不要令牌」二档,没法表达这种层次。四档鉴权模式就是为这种层次设计的——每档对应一类访问要求。

二、四档一览

请求进来
   │
   ▼ 看目标路由的 auth 模式
   │
   ├─ none ──► 不鉴权,直接处理
   ├─ client ──► 要有效 bearer 令牌(任意 scope)
   ├─ host ──► 要宿主令牌 或 owner 级 bearer
   └─ host-token ──► 要宿主令牌
​

三、none:公开资源

none 模式的资源不需要任何鉴权。典型例子:

• 健康检查端点(让监控系统探活)
• 能力声明(让任何客户端知道服务端能干啥)
• 其他刻意公开的信息

这些资源「公开无害」,要令牌反而增加无谓门槛。

四、client:任意有效令牌

client 模式要求请求带一个有效的 bearer 令牌,但不限制令牌的 scope(任何 scope 都行,只要有效)。典型场景:

• 普通浏览(查看工作区列表、读会话)
• 任何登录用户都能做的操作

这档是「确认你是合法用户」,但不细分你是 owner 还是 viewer——那是下一节 scope 的事。

五、host:宿主级

host 模式要求宿主令牌 或 owner 级 bearer。这档用于「宿主专属操作」——只有工作区所有者(或其签发的宿主令牌)才能做。典型场景:

• 管理操作(改工作区配置、签发令牌)
• 涉及安全/隐私的操作

注意 host 接受两种凭据:宿主令牌(所有者本机的特殊令牌)或 owner 级 bearer(所有者签发的令牌里 scope=owner 的)。这俩都代表「所有者级身份」。

六、host-token:明确宿主令牌

host-token 模式只接受宿主令牌(不接受 owner bearer)。这比 host 更严格——必须是「宿主本机令牌」,不能是「所有者签发的 bearer」。用于「最敏感、必须本机」的操作。

💡 host vs host-token 的细微差别:host 接受「宿主令牌 或 owner bearer」(两种身份都行),host-token 只接受「宿主令牌」(必须本机)。前者宽松些,后者最严。这种细分让最敏感的操作只能本机做,不能被远程 owner bearer 调。

七、鉴权模式与路由注册

每条路由注册时声明它的 auth 模式(第 3 章 01 节的路由结构含 auth 字段)。服务端匹配路由后,按声明的模式鉴权:

路由: { path: "/workspace/:id", auth: "client", ... }
   │
   ▼ 请求匹配到这条路由
   │
   ▼ 按 auth="client" 鉴权
   │
   ├─ 请求带有效 bearer ──► 通过
   └─ 没带/无效 ──► 401
​

注意:鉴权模式主要用于路由注册声明与日志。实际鉴权逻辑由几个鉴权函数实现(requireClient/requireHost/requireHostToken),它们在 handler 执行前被调用。

八、鉴权失败的响应

鉴权不通过,服务端返回标准 HTTP 错误码:

这让客户端能区分「没登录(401)」和「登录了但没权限(403)」,分别处理。

九、本节要点回顾

1. 四档鉴权:none / client / host / host-token,覆盖不同访问要求。
2. none:公开资源,不要令牌。
3. client:任意有效 bearer,「确认是合法用户」。
4. host:宿主令牌 或 owner bearer,宿主专属。
5. host-token:只接受宿主令牌,最严,必须本机。
6. 路由注册声明 auth:匹配后按声明鉴权;实际逻辑由鉴权函数实现。
7. 失败响应:401(未授权)/ 403(禁止)。

四档模式讲清了,下一节讲令牌的「权力范围」——三级权限作用域。