【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载本文基于 OpenShell 的 RFC 0010 附录 extension-authentication.md讲解 Gateway Interceptor 在 Alpha 阶段实际落地的扩展认证机制短期 Ed25519 Bearer JWT 如何签发与验证、audience的默认派生与一致性断言、Unix 套接字与 HTTPS 双传输形态以及allow_insecure_transport兼容开关。读完之后你将理解 gateway 与 interceptor 之间的信任边界设计并能对照仓库源码crates/openshell-gateway-interceptors、crates/openshell-extension-core验证每一项声明。背景RFC 0010 的认证要求与本附录的取代关系RFC 0010Gateway Interceptors在“Gateway interceptor endpoints”一节中规定所有 gateway interceptor 连接都必须经过认证具体认证模型当时被声明为 RFC 范围之外但建议实现同时支持 mTLS 与 bearer-token 两种认证方式。本附录记录了 Alpha 阶段真正构建的机制并明确取代正文中的该段描述RFC 其余部分保持不变。理解这一点很重要如果你只读 RFC 正文会以为 mTLS 与 bearer-token 是同等优先级的两条路线实际上 Alpha 版本只交付了 bearer-token 一半mTLS 被推迟为后续加固项。另一个关键事实是Gateway Interceptor 与 Supervisor Middleware 共享同一套认证实现。完整的 claim 契约、授权模型、密钥分发和剩余风险只记录在 RFC 0009 的附录中本附录只记录 interceptor 场景下的差异点。下文引用 claim 字段语义时均以 RFC 0009 附录的 claim 契约表为准。Alpha 交付内容Bearer Token 而非 mTLSAlpha 版本交付的是 RFC 正文建议中的 bearer-token 部分而非 mTLS 部分。具体行为是Gateway 在启动时从自身配置中签发mint凭证并可原地轮换in-place rotation该 JWT 会附加到对 interceptor 的三类调用上Describe、Evaluate以及 provider-profile 快照调用mTLS 保留为后续加固工作。与 Supervisor Middleware 场景不同interceptor只会被 gateway 调用。因此有两个结构上的简化每个 token 都携带caller_kind: gateway且不含sandbox_id不存在 supervisor 侧的凭证分发路径Middleware 场景中 sandbox supervisor 需要通过RefreshSandboxTokenRPC 按操作者注册名请求凭证也不存在基于策略的授权步骤——gateway 从自己的配置中自行铸造凭证。源码印证了这两点。crates/openshell-extension-core/src/jwt.rs 定义了扩展 JWT 的 claim 结构ExtensionJwtClaims其中sandbox_id是Option且序列化时被跳过/// JWT claim set accepted by external extension services. pub struct ExtensionJwtClaims { pub iss: String, pub aud: String, pub sub: String, pub iat: i64, pub exp: i64, pub jti: String, pub caller_kind: ExtensionCallerKind, #[serde(skip_serializing_if Option::is_none)] pub sandbox_id: OptionString, }该文件的单元测试gateway_claims_omit_sandbox_id直接验证了附录的声明gateway 场景下的 claim JSON 中不存在sandbox_id字段且caller_kind的线格式为gateway枚举值以 snake_case 稳定序列化测试caller_kind_uses_stable_snake_case_wire_values覆盖。此外jwt.rs中还有两个与认证语义直接相关的常量附录的“短期”“精确受众”要求都落在这些实现上常量值含义MAX_EXTENSION_TOKEN_TTL1 小时扩展 token 的最大接受寿命即使遗留 sandbox bootstrap 凭证可以不设过期时间跨 gateway 信任边界的扩展凭证也必须保持短期。EXTENSION_JWT_TYPopenshell-extjwtJOSE header 中显式的typ值见下文。关于“短期”的上界RFC 0009 附录的 claim 契约表规定iat/exp的寿命有界、最长一小时源码中的MAX_EXTENSION_TOKEN_TTL Duration::from_hours(1)与此一致。为什么要有显式typ针对最常见验证器错误的纵深防御扩展 token 与 sandbox-to-gateway 准入 token 由同一把密钥签名。如果验证器只靠 audience 区分一旦漏检aud就可能误接受 sandbox bootstrap 凭证。因此所有扩展 bearer token 在 JOSE header 中携带显式typ: openshell-extjwtRFC 8725 section 3.11 的显式类型化一个要求该typ的验证器即使忘记检查aud也无法接受 sandbox bootstrap 凭证。需要强调的边界是——这是针对最可能验证器错误的纵深防御不是 audience 校验的替代品。传输形态保留 Unix 域套接字这是 interceptor 与 middleware 的重要差异。Middleware 端点必须同时可达 gateway 和所有 sandbox supervisor因此 gateway 本地套接字不可用只能走 HTTPS平台信任根或操作者提供的 CA bundle配合正常的证书与端点主机名校验。而 interceptor只由 gateway 这一个调用方使用所以 RFC 正文中的 Unix 域套接字选项被保留下来。在配置了 gateway JWT 签名时https://与unix://端点都被接受unix://gateway 本地套接字只有唯一调用方可达无需跨网络加密https://可以固定pin操作者提供的 CA bundle并保留正常的主机名校验。这一语义在配置结构中有对应crates/openshell-core/src/config.rs 中的GatewayInterceptorConfig文档注释写明grpc_endpoint支持http://、https://和unix://三类端点并提供tls_ca_cert_path字段用于 HTTPS 端点的 PEM 信任根 bundle/// One configured gateway interceptor service. pub struct GatewayInterceptorConfig { /// Operator-assigned instance name used in logs and config overrides. pub name: String, /// Interceptor gRPC endpoint. Supports http://, https://, and /// unix:// endpoints. pub grpc_endpoint: String, /// Optional PEM trust-root bundle for an HTTPS endpoint. #[serde(default)] pub tls_ca_cert_path: OptionPathBuf, /// Exact JWT audience for this service. When omitted, a kind-scoped value /// is derived from the configured registration name. #[serde(default)] pub audience: OptionString, /// Opt out of extension authentication for this interceptor, permitting a /// plaintext http:// endpoint with no bearer credential. #[serde(default)] pub allow_insecure_transport: bool, // ... order / failure_policy / timeout / max_response_bytes / // max_patches / binding_policy / bindings }Audience 契约默认派生、显式覆盖、启动期一致性断言这是附录中最具操作价值的一段。契约分三步默认 audience为urn:openshell:extension:interceptor:name其中name是配置中的 interceptor 注册名也可以在配置中为每个 interceptor 显式指定audience。Interceptor 可以在其Describemanifest 的expected_audience字段中声明它验证的 audience。在已认证的Describe成功之后gateway 把该字段视为一致性断言consistency assertion若其值与配置的 audience 不一致gateway拒绝启动。实现位于 crates/openshell-gateway-interceptors/src/plan.rs/// After authenticated Describe succeeds, reject an interceptor whose /// configured audience differs from the one the service says it verifies. /// /// This is a post-authentication consistency assertion, not audience discovery: /// a strict verifier may reject an incorrect audience before returning its /// manifest. A service that does not advertise an audience is accepted unchanged. fn validate_expected_audience( config: GatewayInterceptorConfig, advertised: str, authenticated: bool, ) - Result() { if !authenticated || config.allow_insecure_transport || advertised.is_empty() { return Ok(()); } let configured config.resolved_audience(); if advertised ! configured { return Err(InterceptorError::Config(format!( interceptor {} expects audience {advertised} but the gateway \ is configured to mint {configured}, config.name ))); } Ok(()) }该函数被 ExecutionPlan::load 在每个 interceptor 的Describe调用成功后调用即执行计划构建阶段——也就是 gateway 开始服务流量之前。这正好符合附录引用的姿态RFC 正文已经把“服务不可用、manifest 无效、未授权绑定”都定义为启动失败因此 interceptor 配置问题在 gateway 服务流量之前就会暴露而不是运行期静默失效。三个实现细节值得注意这不是 audience 发现。严格验证器可能在返回 manifest 之前就拒绝 audience 不匹配的 token此时 OpenShell 只能观察到一个认证失败expected_audience只做事后一致性校验。空字段被跳过advertised.is_empty()时直接放行对未声明 audience 的存量服务完全向后兼容。allow_insecure_transport true的注册项也直接跳过该校验因为此类注册不附带任何凭证见下文。默认 audience 的派生逻辑在 GatewayInterceptorConfig::resolved_audience/// Resolve the configured JWT audience to its deterministic default. pub fn resolved_audience(self) - Cow_, str { self.audience .as_deref() .filter(|audience| !audience.is_empty()) .map_or_else( || Cow::Owned(format!(urn:openshell:extension:interceptor:{}, self.name)), Cow::Borrowed, ) }注意.filter(|audience| !audience.is_empty())显式配置的空字符串 audience 会回退到默认派生值而不是使用空串该行为有对应单元测试config.rs 中关于resolved_audience的断言 验证了空 audience 归一化为urn:openshell:extension:interceptor:governance。配置示例可参考 gateway 配置参考文档 与 gateway interceptor 扩展文档其中给出了 audience 的完整配置形态。兼容性allow_insecure_transport逃逸开关为了保持本地开发和存量部署可用interceptor 可以设置allow_insecure_transport true从而保留一个不附带任何凭证的明文http://端点。gateway 会在每次启动时记录一条点名该 interceptor 的警告日志。该开关存在的目的被明确限定为两类场景本地开发以及扩展认证机制出现之前就已配置完成的部署。源码中有两处对应实现都在 plan.rs禁用凭证附加。在ExecutionPlan::load中当注册了 token 槽位但该 interceptor 声明allow_insecure_transport时通道直接使用禁用的 interceptor不附加任何 bearer 凭证let interceptor match token_slots.as_ref() { Some(_) if config.allow_insecure_transport BearerTokenInterceptor::disabled(), Some(slots) slots .get(config.name) .ok_or_else(|| { /* 缺少 bearer-token slot 时启动失败 */ })? .interceptor(), None BearerTokenInterceptor::disabled(), };fail-closed 的槽位校验。validate_authenticated_slots 保证只要 gateway 配置了 token 槽位即启用了扩展认证每一个没有声明allow_insecure_transport的 interceptor 都必须持有对应的 bearer-token slot否则直接报Config错误拒绝启动。注释写得很直白“操作者选择退出扩展认证的注册项故意没有 slot其余所有情况必须 fail closed。”也就是说认证是默认开启且 fail-closed的要么配置了 slot 并正确签发凭证要么显式声明退出认证并接受每次启动的警告不存在“静默地不认证”的中间态。推迟项Deferred以下工作明确不属于 Alpha 范围作为后续跟进项记录与 RFC 0009 附录一致mTLS 客户端认证带重叠窗口overlap window的多密钥轮换超出“短有效期”之外的防重放能力。剩余风险同样以 RFC 0009 附录为权威描述对 interceptor 场景同样适用主要包括token 有效期内被窃取的 bearer token 可被重放jti用于关联但 OpenShell 不跟踪、不吊销扩展凭证与 sandbox 准入凭证共享同一签名密钥与kid靠 audience 与typ隔离但无法独立轮换单密钥 JWKS 没有轮换重叠窗口以及缺少通道绑定channel binding。小结运维视角的检查清单结合附录与源码部署带认证的 Gateway Interceptor 时可按以下顺序核对确认 gateway JWT 签名已配置存在 token 槽位否则认证 interceptor 会在 validate_authenticated_slots 处启动失败不配置audience时按urn:openshell:extension:interceptor:name派生resolved_audienceinterceptor 侧验证逻辑必须使用同一个精确 audience若 interceptor 在 manifest 中声明expected_audience确保它与 gateway 侧配置一致否则 gateway 拒绝启动validate_expected_audience本地开发或存量明文端点显式设置allow_insecure_transport true并预期每次启动出现点名警告生产传输优先选择unix://gateway 本地或带 CA bundle 固定的https://mTLS 客户端认证等待后续版本。整个机制的设计取向与 RFC 0010 正文的失败姿态一脉相承认证与配置问题在 gateway 服务流量之前就暴露为启动失败运行期不再存在“未认证但可用”的 interceptor 通道。赞分享【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载相关推荐OpenShell Supervisor Middleware 协议扩展设计一元 v1 契约、未来流式操作、操作相位与认证传输OpenShell Supervisor Middleware 协议扩展设计一元 v1 契约、未来流式操作、操作相位与认证传输 OpenShell 的 supOpenShell Supervisor Middleware 扩展认证AlphaTLS 信任根与短时效精确受众 Ed25519 JWT 的双向信任机制OpenShell Supervisor Middleware 扩展认证AlphaTLS 信任根与短时效精确受众 Ed25519 JWT 的双向信任机制Cosmos3-Super-Text2Image-4Step常见问题解答解决你的图像生成难题Cosmos3 Super Text2Image 4Step常见问题解答解决你的图像生成难题 Cosmos3 Super Text2Image 4Step是一人工智能大模型基础模型媒体生成多模态上一篇Redux Thunk错误处理策略比较集中vs分散下一篇Audacity 音频编辑完全入门指南5 步把嘈杂人声录音频变成可发布的作品创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考