Servify Docs

Appearance

Auth Surface Policy ​

本文定义 Servify HTTP 路由的授权表面分类，目标是把“这个入口到底该不该匿名、该不该走 management token、该不该只允许 service”从零散 handler 逻辑里收口到统一规则。

分类 ​

1. Public Surface ​

适用范围：

  • 面向匿名访问者、浏览器或终端用户的公开读接口
  • 只暴露最小只读能力或建连能力

约束：

  • 不依赖 management JWT
  • 不承载后台管理写操作
  • 必须有独立的安全评审和路径级限流基线

当前路由：

  • /health
  • /ready
  • /public/portal/config
  • /public/kb/*
  • /public/csat/*
  • /api/v1/ws
  • /uploads/*

2. Auth Surface ​

适用范围：

  • 认证与会话自助相关入口
  • 允许匿名进入认证前置流程，或允许已登录用户管理自己的 auth session

约束：

  • 匿名入口必须具备独立路径级限流
  • 已登录自助入口只允许操作自己的认证状态，不复用 management surface 的资源写权限
  • 不承载跨用户、跨租户的后台管理动作

当前路由：

  • 匿名认证入口：/api/v1/auth/login、/api/v1/auth/register、/api/v1/auth/refresh
  • 已登录自助入口：/api/v1/auth/me、/api/v1/auth/sessions、/api/v1/auth/sessions/logout-current、/api/v1/auth/sessions/logout-others

3. Management Surface ​

适用范围：

  • 管理后台、客服工作台、运营查询、人工触发的后台动作

约束：

  • 必须经过 AuthMiddleware
  • principal kind 仅允许 agent、admin、service
  • 资源级访问继续叠加 RequireResourcePermission(...)
  • 不允许 end_user token 进入该表面

当前路由：

  • /api/*
  • /api/v1/ws/stats
  • /api/v1/webrtc/*
  • /api/v1/messages/platforms
  • /api/v1/ai/*

4. Service Surface ​

适用范围：

  • 机器到机器调用、采集上报、受控集成入口

约束：

  • 必须经过 AuthMiddleware
  • principal kind 仅允许 service
  • 不复用 management agent/admin token
  • 应优先设计成窄契约、低权限、可独立限流的入口

当前路由：

  • /api/v1/metrics/ingest

新增路由准入规则 ​

新增 HTTP 路由时，先回答这 4 个问题，再决定挂到哪个 surface：

  1. 调用方是谁：匿名用户、终端用户、客服/管理员，还是服务账号？
  2. 这个入口是公开读取、认证前置、后台管理，还是机器上报？
  3. 失败时应该返回 401、403，还是允许匿名继续进入业务校验？
  4. 是否需要专属路径级 rate limit，而不是只依赖全局限流？

默认策略：

  • 拿不准时，不要直接挂到匿名 public surface
  • 认证相关入口优先进入 auth surface，而不是混进 public 或 management
  • 管理动作优先进入 management surface
  • 机器上报、回调、采集优先进入 service surface

实现落点 ​

后续扩展 ​

  • 如果未来出现真正的 end-user authenticated business API，应新增独立 surface，而不是回退复用 management surface
  • 如果引入回调签名、API key 或 mTLS，可在 service surface 内继续细分
  • 如果开放接口继续增多，应把 security surface catalog 扩展成自动审查和审批流的输入源