认证边界策略

NENE2 将认证视为显式的应用边界，而非隐藏的框架魔法。

本策略定义了机器客户端、MCP 工具和未来认证中间件的首个 API 密钥和令牌方向。

定位

认证和授权是显式的中间件边界。

默认方向：

• API 密钥用于机器客户端和 MCP 工具。
• Bearer 令牌用于应用采用时的用户或服务认证。
• 会话认证属于需要服务端浏览器会话的应用。
• 只有当匹配的中间件行为存在时，才应添加 OpenAPI 安全方案。
• 密钥绝不能被提交、记录日志或通过 MCP 元数据暴露。

首个实现的中间件路径是针对机器客户端端点的 API 密钥检查，使用：

X-NENE2-API-Key

密钥值在配置时从 NENE2_MACHINE_API_KEY 加载。仅公开本地开发时留空，测试受保护路由时在仓库外设置。

API 密钥

API 密钥是非人类客户端的长期凭证。

使用 API 密钥的场景：

• 调用本地 HTTP API 的本地 MCP 工具
• 服务间检查工具
• 需要稳定范围访问的机器客户端

API 密钥应具备：

• 所有者
• 环境
• 范围列表
• 创建时间
• 存储存在时的最后使用时间
• 轮换或吊销路径

不要将原始 API 密钥放入 OpenAPI 示例、MCP 工具目录、日志、截图或已提交的配置中。

Bearer 令牌

Bearer 令牌是在 Authorization 请求头中发送的请求凭证。

使用 Bearer 令牌的场景：

• 短期用户令牌
• 具有显式范围的服务令牌
• 未来的 OAuth 或第一方令牌流

即使 Bearer 令牌是短期的，也应将其视为密钥。

框架在认证适配器存在之前不应规定令牌格式。

范围

范围描述允许的能力。

初始范围命名应保持小而可读：

• read:system
• read:health
• read:docs
• write:* 仅在写工具设计完成后
• admin:* 仅在管理策略文档化后

MCP 工具应在生产使用前声明其所需的最小范围。

本地开发

本地开发仅在凭证明确非机密且记录为示例时，才可使用占位符凭证。

本地工具可以：

• 在端点为公开时不带凭证调用公开本地 HTTP 端点
• 使用在仓库外生成的仅测试 API 密钥
• 记录所需的环境变量名称但不包含值

本地工具不得：

• 通过 MCP 工具读取 .env 值
• 在命令输出中打印凭证
• 依赖开发者的私有凭证存储
• 以类似生产行为的方式绕过认证

生产预期

生产认证在实施前需要显式设计。

启用生产凭证前，记录：

• 凭证类型
• 所有者和轮换流程
• 允许的环境
• 所需范围
• 存储后端
• 审计字段
• 缺失、无效、过期或不足凭证的失败行为

凭证验证失败应使用 Problem Details 响应，且不得透露密钥值是否存在。

日志和可观测性

日志可包含：

• 请求 ID
• 凭证类型
• 安全时的凭证所有者 ID
• 范围名称
• 认证结果
• 失败原因类别

日志不得包含：

• 原始 API 密钥
• Bearer 令牌
• Cookie
• 授权请求头
• 凭证哈希

OpenAPI 和 MCP

OpenAPI 安全方案应与已实现的中间件匹配。

添加时，OpenAPI 应描述：

• 凭证位置
• 所需范围
• 401 和 403 Problem Details 响应
• 不含真实密钥的示例

MCP 元数据应引用所需范围，而非原始凭证。

写入、管理和破坏性 MCP 工具在实施前需要认证、授权、审计、请求 ID 传播和确认行为。