Pre-alpha 文档

授权一个 MCP Resource，不扩大信任边界。

配置 StateKnot Challenge-driven MCP OAuth Client、持久化 Credential Store、精确 Callback 边界、有界 Replay 与冻结官方证据。

将 OAuth 绑定到一个精确 Resource

生产 MCP Resource 强制 HTTPS。Host 提供可信 User Agent，以及加密、 Tenant-scoped Credential Store 与带 Expiry 的 PKCE State Store。In-memory Constructor 只适用于明确不承诺跨重启恢复的进程。

Rust · OAuth 凭据持久化 Binding

use std::sync::Arc;

use stateknot_integrations::{
    McpClient, McpClientIdentity, McpClientOptions,
    McpOAuthAuthorization, McpOAuthOptions, McpOAuthRegistration,
    McpOAuthResource, ProviderEndpoint,
};

let endpoint = ProviderEndpoint::https("https://mcp.example.com/mcp/")?;
let resource = McpOAuthResource::from_endpoint(&endpoint)?;
let registration = McpOAuthRegistration::client_metadata_document(
    "https://agent.example.com/oauth/client-metadata.json",
)?;
let policy = McpOAuthOptions::native(
    "http://127.0.0.1:49152/callback",
    "Inventory Agent",
    registration,
)?;
let authorization = Arc::new(
    McpOAuthAuthorization::new_with_stores(
        resource,
        policy,
        user_agent,
        encrypted_credential_store,
        expiring_pkce_state_store,
    )
    .await?,
);

let client = McpClient::connect(
    endpoint,
    McpClientIdentity::new("inventory-agent", "1.0.0")?,
    authorization,
    McpClientOptions::default().with_maximum_authorization_retries(1)?,
)
.await?;

Credential 由外部 Provision 时使用 Pre-registration；发布 HTTPS Client Metadata Document 时使用 CIMD；只有部署 Policy 明确接受时才启用 DCR Fallback。

让 Challenge Recovery 保持有限

不存在可用 Credential 时，Client 先匿名发送。
有界 401/403 Bearer Challenge 驱动 Protected-resource 与 Authorization-server Discovery。
StateKnot 恢复 Issuer-bound Credential，或按照 Policy 通过 Pre-registration、CIMD、DCR 启动 PKCE Flow。
Host 打开已校验 Authorization URL，并从精确注册 Origin 与 Path 返回完整 Callback URL。
Token Exchange 成功后，用新 JSON-RPC ID 重放一次 MCP Method。Timeout 与 Ambiguous Dispatch 永不重放。

403 只有携带 Scope 的显式 insufficient_scope Challenge 才能触发 Step-up。Scope Upgrade 与 Transport Replay 分别拥有独立硬上限。Issuer 变化会强制启动新的 Issuer-bound Registration Flow。

由 Host 持有 User-agent 边界

Native Host 在打开 Browser 前占用 Loopback Listener，只接受配置的 Address、 Port 与 Path，返回一次完整 Callback URL 后关闭 Listener。StateKnot 强制 5 分钟默认 Handoff Timeout、精确 Callback Binding、PKCE、State、RFC 8707 Resource Indicator 与 RFC 9207 Issuer Check。URL、Code、Verifier、Client Identity 与 Token 绝不能进入 Log。

把 Store 当作安全基础设施

加密保存 Access Token、Refresh Token、Client Secret 与 PKCE State，并具备 Key Rotation Procedure。
按 Tenant、Principal、MCP Resource 与 Authorization-server Issuer 隔离记录。
State 必须一次性且会过期；Credential Replacement 必须原子执行。
Discovery、Registration、Refresh、Migration、Scope Upgrade、Cancellation 与 Failure 只产生脱敏 Audit Fact。

复现精确声明

Shell · 本地 Contract 与冻结官方门禁

cargo test -p stateknot-integrations --test mcp_client_contract --locked
bash conformance/mcp-client/run-2026-07-28.sh

冻结门禁通过全部 32 个计分 Client 场景，其中包括全部 25 个 OAuth 场景：371 项计分 Assertion Success、0 Failure。7 个官方明确不计分的 Extension 单独报告，不进入支持声明。请阅读完整证据边界与完整运维合约。