mcp-test-authz 0.1.0__tar.gz

mcp_test_authz-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.5
+Name: mcp-test-authz
+Version: 0.1.0
+Summary: Authz probe MCP server (stdio) covering L2/L3 auth modes
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: mcp>=2.0.0

mcp_test_authz-0.1.0/dev_auth_server.py

@@ -0,0 +1,332 @@
+"""本地演示用授权服务器（Authorization Server, AS）—— 仅供本地联调
+
+用途
+----
+让「鉴权探针」示例在本机完整跑通。本脚本同时支持两种 grant，覆盖 L3 的两种 OAuth 形态：
+
+- `client_credentials`：服务身份令牌（对应 L3 的 client_credentials 模式）；
+- `urn:ietf:params:oauth:grant-type:token-exchange`（RFC 8693）：用 `subject_token`
+  （终端用户访问令牌）换取**委派令牌**——`sub` 取自用户、`act` 记录本 MCP、`aud` 绑定上游。
+
+此外提供 `POST /demo/user-token`，便于本地演示时快速签一枚**用户 subject token**
+（其 `aud` 指向「AgentArts 网关」标识，**不等于**上游资源——正是这一点让「透传用户令牌」
+到上游会被 401 拒绝，说明必须做 token-exchange 而非透传）。
+
+生产环境请改用 Keycloak / 企业 IdP 等成熟授权服务器，不要使用本脚本。
+
+实现
+----
+仅依赖 Python 标准库（http.server），无需安装任何包。签发 HS256 JWT。
+
+启动
+----
+    python dev_auth_server.py --secret dev-authz-secret \
+        --issuer https://auth.example.com \
+        --resource https://upstream.demo.example.com \
+        --gateway-audience https://agentarts.example.com \
+        --actor service:authz-mcp
+
+端点
+----
+- GET  /.well-known/oauth-authorization-server   授权服务器元数据（RFC 8414）
+- POST /token                                   令牌端点（client_credentials / token-exchange）
+- POST /demo/user-token                         演示：签发用户 subject token（body: {"sub":"alice"}）
+- POST /introspect                              令牌内省（演示用，返回是否有效）
+- GET  /                                        说明页
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import hmac
+import json
+import time
+import urllib.parse
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+# RFC 8693 常量
+TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange"
+ACCESS_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token"
+
+# --------------------------------------------------------------------------- #
+# 配置（可被命令行参数覆盖）
+# --------------------------------------------------------------------------- #
+CONFIG = {
+    "secret": "dev-authz-secret",
+    "issuer": "https://auth.example.com",
+    "resource": "https://upstream.demo.example.com",     # 上游资源标识（委派/服务令牌的 aud）
+    "gateway_audience": "https://agentarts.example.com",  # AgentArts 网关标识（用户令牌的 aud）
+    "actor": "service:authz-mcp",                         # 本 MCP 的服务身份（委派令牌的 act）
+    "client_id": "authz-mcp-client",
+    "client_secret": "authz-mcp-secret",
+    "scopes": ["demo:read", "demo:write"],
+    "token_ttl": 3600,
+    "user_token_ttl": 1800,
+}
+
+
+# --------------------------------------------------------------------------- #
+# JWT(HS256) 工具
+# --------------------------------------------------------------------------- #
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _b64url_decode(seg: str) -> bytes:
+    seg += "=" * (-len(seg) % 4)
+    return base64.urlsafe_b64decode(seg.encode("ascii"))
+
+
+def sign_jwt(claims: dict) -> str:
+    header = {"alg": "HS256", "typ": "JWT"}
+    seg = ".".join(
+        _b64url(json.dumps(part, separators=(",", ":"), ensure_ascii=False).encode("utf-8"))
+        for part in (header, claims)
+    )
+    sig = hmac.new(CONFIG["secret"].encode("utf-8"), seg.encode("ascii"), hashlib.sha256).digest()
+    return f"{seg}.{_b64url(sig)}"
+
+
+def issue_service_token(scope: str, client_id: str) -> dict:
+    """client_credentials：服务身份令牌（aud=上游资源，无 act）。"""
+    now = int(time.time())
+    claims = {
+        "iss": CONFIG["issuer"],
+        "sub": CONFIG["actor"],          # 服务身份就是主体
+        "aud": CONFIG["resource"],
+        "client_id": client_id,
+        "scope": scope,
+        "iat": now,
+        "exp": now + CONFIG["token_ttl"],
+    }
+    return {
+        "access_token": sign_jwt(claims),
+        "token_type": "Bearer",
+        "expires_in": CONFIG["token_ttl"],
+        "scope": scope,
+    }
+
+
+def issue_user_token(sub: str) -> dict:
+    """演示：签发一枚**用户 subject token**，其 aud 指向 AgentArts 网关（非上游资源）。"""
+    now = int(time.time())
+    scope = "openid profile"
+    claims = {
+        "iss": CONFIG["issuer"],
+        "sub": sub,
+        "aud": CONFIG["gateway_audience"],   # 受众是网关，不是上游
+        "client_id": "agentarts-gateway",
+        "scope": scope,
+        "iat": now,
+        "exp": now + CONFIG["user_token_ttl"],
+    }
+    return {
+        "access_token": sign_jwt(claims),
+        "token_type": "Bearer",
+        "expires_in": CONFIG["user_token_ttl"],
+        "scope": scope,
+    }
+
+
+def issue_delegated_token(sub: str, scope: str, audience: str) -> dict:
+    """token-exchange：委派令牌 —— sub=用户、act=本 MCP、aud=上游资源。"""
+    now = int(time.time())
+    claims = {
+        "iss": CONFIG["issuer"],
+        "sub": sub,                        # 终端用户身份
+        "act": CONFIG["actor"],            # 代理方：本 MCP 服务身份（代理链）
+        "aud": audience,                   # 受众：上游资源
+        "client_id": CONFIG["client_id"],
+        "scope": scope,
+        "iat": now,
+        "exp": now + CONFIG["token_ttl"],
+    }
+    return {
+        "access_token": sign_jwt(claims),
+        "issued_token_type": ACCESS_TOKEN_TYPE,
+        "token_type": "Bearer",
+        "expires_in": CONFIG["token_ttl"],
+        "scope": scope,
+    }
+
+
+def verify_subject_token(token: str) -> tuple[dict | None, str]:
+    """校验入站 subject_token：签名 + iss + exp。返回 (claims, error)。"""
+    if not token:
+        return None, "缺少 subject_token"
+    try:
+        head_b64, payload_b64, sig_b64 = token.split(".")
+    except ValueError:
+        return None, "subject_token 格式错误"
+
+    signing_input = f"{head_b64}.{payload_b64}".encode("ascii")
+    expected = hmac.new(CONFIG["secret"].encode("utf-8"), signing_input, hashlib.sha256).digest()
+    try:
+        given = _b64url_decode(sig_b64)
+    except Exception:  # noqa: BLE001
+        return None, "subject_token 签名解码失败"
+    if not hmac.compare_digest(expected, given):
+        return None, "subject_token 签名校验失败"
+
+    try:
+        claims = json.loads(_b64url_decode(payload_b64))
+    except Exception:  # noqa: BLE001
+        return None, "subject_token 载荷解析失败"
+
+    if claims.get("iss") != CONFIG["issuer"]:
+        return None, "subject_token 签发者(iss)不受信任"
+    if int(claims.get("exp", 0)) < int(time.time()):
+        return None, "subject_token 已过期"
+    return claims, ""
+
+
+# --------------------------------------------------------------------------- #
+# HTTP 处理
+# --------------------------------------------------------------------------- #
+class Handler(BaseHTTPRequestHandler):
+    server_version = "DevAuthServer/1.0"
+
+    def log_message(self, fmt: str, *args) -> None:  # noqa: A003
+        print("[dev-as] " + fmt % args)
+
+    def _json(self, status: int, payload: dict) -> None:
+        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _read_json(self) -> dict:
+        length = int(self.headers.get("Content-Length", "0") or 0)
+        if not length:
+            return {}
+        try:
+            return json.loads(self.rfile.read(length).decode("utf-8"))
+        except Exception:  # noqa: BLE001
+            return {}
+
+    def do_GET(self) -> None:  # noqa: N802
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path == "/.well-known/oauth-authorization-server":
+            self._json(200, {
+                "issuer": CONFIG["issuer"],
+                "token_endpoint": f"{CONFIG['issuer']}/token",
+                "introspection_endpoint": f"{CONFIG['issuer']}/introspect",
+                "grant_types_supported": ["client_credentials", TOKEN_EXCHANGE_GRANT],
+                "token_endpoint_auth_methods_supported": ["client_secret_post"],
+                "scopes_supported": CONFIG["scopes"],
+            })
+            return
+        self._json(200, {
+            "service": "Dev Authorization Server (仅供本地演示)",
+            "issuer": CONFIG["issuer"],
+            "resource": CONFIG["resource"],
+            "gateway_audience": CONFIG["gateway_audience"],
+            "actor": CONFIG["actor"],
+            "demo_client": {"client_id": CONFIG["client_id"]},
+            "endpoints": [
+                "/.well-known/oauth-authorization-server", "/token", "/demo/user-token", "/introspect",
+            ],
+        })
+
+    def do_POST(self) -> None:  # noqa: N802
+        parsed = urllib.parse.urlparse(self.path)
+
+        if parsed.path == "/demo/user-token":
+            body = self._read_json()
+            sub = str(body.get("sub") or "alice")
+            self._json(200, issue_user_token(sub))
+            return
+
+        length = int(self.headers.get("Content-Length", "0") or 0)
+        form = dict(urllib.parse.parse_qsl(self.rfile.read(length).decode("utf-8")))
+
+        if parsed.path == "/token":
+            self._handle_token(form)
+            return
+        if parsed.path == "/introspect":
+            self._json(200, {"active": bool(form.get("token"))})
+            return
+        self._json(404, {"error": "not_found"})
+
+    def _check_client(self, form: dict) -> bool:
+        cid = form.get("client_id", "")
+        csec = form.get("client_secret", "")
+        # 常量时间比较，避免时序侧信道
+        return hmac.compare_digest(cid, CONFIG["client_id"]) and hmac.compare_digest(
+            csec, CONFIG["client_secret"]
+        )
+
+    def _handle_token(self, form: dict) -> None:
+        grant = form.get("grant_type")
+
+        if grant == "client_credentials":
+            if not self._check_client(form):
+                self._json(401, {"error": "invalid_client"})
+                return
+            scope = form.get("scope") or " ".join(CONFIG["scopes"])
+            self._json(200, issue_service_token(scope, form.get("client_id", "")))
+            return
+
+        if grant == TOKEN_EXCHANGE_GRANT:
+            if not self._check_client(form):
+                self._json(401, {"error": "invalid_client"})
+                return
+            subject_token = form.get("subject_token", "")
+            subject_type = form.get("subject_token_type") or ACCESS_TOKEN_TYPE
+            if subject_type != ACCESS_TOKEN_TYPE:
+                self._json(400, {"error": "invalid_request",
+                                 "error_description": f"不支持的 subject_token_type：{subject_type}"})
+                return
+            claims, err = verify_subject_token(subject_token)
+            if err:
+                self._json(400, {"error": "invalid_grant", "error_description": err})
+                return
+            audience = form.get("audience") or form.get("resource") or CONFIG["resource"]
+            scope = form.get("scope") or " ".join(CONFIG["scopes"])
+            sub = str(claims.get("sub") or "unknown")
+            self._json(200, issue_delegated_token(sub, scope, audience))
+            return
+
+        self._json(400, {"error": "unsupported_grant_type",
+                         "error_description": "本演示授权服务器支持 client_credentials 与 token-exchange"})
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="本地演示用 OAuth 2.1 授权服务器（client_credentials + token-exchange）"
+    )
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=9000)
+    parser.add_argument("--secret", default=CONFIG["secret"])
+    parser.add_argument("--issuer", default=CONFIG["issuer"])
+    parser.add_argument("--resource", default=CONFIG["resource"])
+    parser.add_argument("--gateway-audience", default=CONFIG["gateway_audience"])
+    parser.add_argument("--actor", default=CONFIG["actor"])
+    parser.add_argument("--client-id", default=CONFIG["client_id"])
+    parser.add_argument("--client-secret", default=CONFIG["client_secret"])
+    args = parser.parse_args()
+
+    CONFIG.update({
+        "secret": args.secret, "issuer": args.issuer.rstrip("/"), "resource": args.resource,
+        "gateway_audience": args.gateway_audience, "actor": args.actor,
+        "client_id": args.client_id, "client_secret": args.client_secret,
+    })
+
+    server = ThreadingHTTPServer((args.host, args.port), Handler)
+    print(f"[dev-as] 监听 http://{args.host}:{args.port}  issuer={CONFIG['issuer']}")
+    print(f"[dev-as] resource(上游)={CONFIG['resource']}  gateway={CONFIG['gateway_audience']}  actor={CONFIG['actor']}")
+    print("[dev-as] 支持 client_credentials 与 token-exchange；/demo/user-token 可签用户 subject token")
+    print("[dev-as] 仅供本地演示，生产请使用 Keycloak 等成熟授权服务器")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        server.shutdown()
+
+
+if __name__ == "__main__":
+    main()

mcp_test_authz-0.1.0/dev_upstream_api.py

@@ -0,0 +1,176 @@
+"""受保护的上游 API（资源服务器 / RS）—— 仅供本地联调
+
+定位
+----
+它是 L3 的终点站：同时接受两种凭证，用于覆盖 UPSTREAM_AUTH_MODE 的三种模式：
+
+- **静态 Key**（`X-Api-Key: <key>`）        —— 对应 `static` 模式；
+- **Bearer JWT**（HS256 验签）             —— 对应 `client_credentials` / `token_exchange` 模式。
+
+对 Bearer JWT，会校验 签名 + iss + aud + exp + scope，并把 `sub`（主体）与 `act`（代理方）
+原样回显——这样调用方一眼就能看出「是谁在代表谁访问上游」。
+
+关键对照：**直接透传用户令牌会被 401 拒绝**
+----------------------------------------
+用户 subject token 的 `aud` 是 **AgentArts 网关标识**，并不等于本上游资源。若把用户令牌原样
+透传过来，下面的 `aud` 校验会把它挡在门外——这就是「受众绑定（RFC 8707）」约束的具体体现。
+
+实现
+----
+仅依赖 Python 标准库（http.server），无需安装任何包。
+
+启动
+----
+    python dev_upstream_api.py --secret dev-authz-secret \
+        --issuer https://auth.example.com \
+        --audience https://upstream.demo.example.com \
+        --static-key dev-static-key
+
+端点
+----
+- GET /echo         回显鉴权结果（via / sub / act / scope / iss / aud）
+- GET /             说明页
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import hmac
+import json
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+CONFIG = {
+    "secret": "dev-authz-secret",
+    "issuer": "https://auth.example.com",
+    "audience": "https://upstream.demo.example.com",
+    "static_key": "dev-static-key",
+    "required_scope": "demo:read",
+}
+
+
+# --------------------------------------------------------------------------- #
+# HS256 JWT 校验（标准库）
+# --------------------------------------------------------------------------- #
+def _b64url_decode(seg: str) -> bytes:
+    seg += "=" * (-len(seg) % 4)
+    return base64.urlsafe_b64decode(seg.encode("ascii"))
+
+
+def verify_bearer(authorization: str | None) -> tuple[dict | None, str]:
+    """校验 Authorization: Bearer <JWT>，返回 (claims, error)。"""
+    if not authorization or not authorization.startswith("Bearer "):
+        return None, "缺少 Bearer 令牌"
+    token = authorization[len("Bearer "):].strip()
+    try:
+        head_b64, payload_b64, sig_b64 = token.split(".")
+    except ValueError:
+        return None, "令牌格式错误"
+
+    signing_input = f"{head_b64}.{payload_b64}".encode("ascii")
+    expected = hmac.new(CONFIG["secret"].encode("utf-8"), signing_input, hashlib.sha256).digest()
+    try:
+        given = _b64url_decode(sig_b64)
+    except Exception:  # noqa: BLE001
+        return None, "签名解码失败"
+    if not hmac.compare_digest(expected, given):
+        return None, "签名校验失败"
+
+    try:
+        claims = json.loads(_b64url_decode(payload_b64))
+    except Exception:  # noqa: BLE001
+        return None, "载荷解析失败"
+
+    if claims.get("iss") != CONFIG["issuer"]:
+        return None, "签发者(iss)不受信任"
+    if claims.get("aud") != CONFIG["audience"]:
+        return None, "令牌受众(aud)与本资源不匹配（禁止把用户 token 直接透传到上游）"
+    if int(claims.get("exp", 0)) < int(time.time()):
+        return None, "令牌已过期"
+    if CONFIG["required_scope"] and CONFIG["required_scope"] not in set(str(claims.get("scope", "")).split()):
+        return None, f"缺少 scope: {CONFIG['required_scope']}"
+    return claims, ""
+
+
+# --------------------------------------------------------------------------- #
+# HTTP 处理
+# --------------------------------------------------------------------------- #
+class Handler(BaseHTTPRequestHandler):
+    server_version = "DevUpstreamAPI/1.0"
+
+    def log_message(self, fmt: str, *args) -> None:  # noqa: A003
+        print("[dev-upstream] " + fmt % args)
+
+    def _json(self, status: int, payload: dict, www_authenticate: str | None = None) -> None:
+        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        if www_authenticate:
+            self.send_header("WWW-Authenticate", www_authenticate)
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _authenticate(self) -> dict | None:
+        """返回鉴权结果字典；失败时已写出响应并返回 None。"""
+        api_key = self.headers.get("X-Api-Key")
+        if api_key is not None:
+            if hmac.compare_digest(api_key, CONFIG["static_key"]):
+                return {"via": "static_key"}
+            self._json(401, {"error": "invalid_api_key", "error_description": "静态 Key 不正确"})
+            return None
+
+        claims, err = verify_bearer(self.headers.get("Authorization"))
+        if err:
+            self._json(401, {"error": "invalid_token", "error_description": err},
+                       www_authenticate=f'Bearer resource_metadata="{CONFIG["audience"]}"')
+            return None
+        return {
+            "via": "jwt",
+            "sub": claims.get("sub"),
+            "act": claims.get("act"),
+            "scope": claims.get("scope"),
+            "iss": claims.get("iss"),
+            "aud": claims.get("aud"),
+            "exp": claims.get("exp"),
+        }
+
+    def do_GET(self) -> None:  # noqa: N802
+        if self.path.rstrip("/") in ("/echo", ""):
+            auth = self._authenticate()
+            if auth is None:
+                return
+            self._json(200, {"ok": True, "path": "/echo", "resource": CONFIG["audience"], **auth})
+            return
+        self._json(404, {"error": "not_found"})
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="受保护的上游 API（本地演示 / L3 终点）")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=9100)
+    parser.add_argument("--secret", default=CONFIG["secret"])
+    parser.add_argument("--issuer", default=CONFIG["issuer"])
+    parser.add_argument("--audience", default=CONFIG["audience"])
+    parser.add_argument("--static-key", default=CONFIG["static_key"])
+    parser.add_argument("--required-scope", default=CONFIG["required_scope"])
+    args = parser.parse_args()
+
+    CONFIG.update({
+        "secret": args.secret, "issuer": args.issuer.rstrip("/"), "audience": args.audience,
+        "static_key": args.static_key, "required_scope": args.required_scope,
+    })
+
+    server = ThreadingHTTPServer((args.host, args.port), Handler)
+    print(f"[dev-upstream] 监听 http://{args.host}:{args.port}  aud={CONFIG['audience']}")
+    print("[dev-upstream] 接受静态 Key(X-Api-Key) 或 aud 匹配、带 scope 的 Bearer 令牌；回显 sub/act")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        server.shutdown()
+
+
+if __name__ == "__main__":
+    main()

mcp_test_authz-0.1.0/issue_token.py

@@ -0,0 +1,79 @@
+"""离线签发示例令牌（仅标准库）—— 用于本地验证 Stdio 鉴权探针。
+
+用途：生成 HS256 JWT，填入 AgentArts Stdio MCP 配置的 `env`：
+    MCP_INBOUND_TOKEN = <本脚本输出的令牌>
+    MCP_AUTH_JWT_SECRET = <与 --secret 相同的密钥>
+
+示例
+----
+# 用户 subject token（aud=AgentArts 网关，用于验证 L2=jwt；也可作为 token_exchange 的 subject）
+python issue_token.py --secret demo-secret --scope "demo:read demo:write" --aud https://agentarts.example.com
+
+# 直接打印可粘贴的 env JSON
+python issue_token.py --secret demo-secret --aud https://agentarts.example.com --env-json
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import time
+from pathlib import Path
+
+# 直接按文件路径加载 _jwt，避免触发包 __init__（进而 import mcp）
+_JWT_PATH = Path(__file__).resolve().parent / "src" / "mcp_authz" / "_jwt.py"
+_spec = importlib.util.spec_from_file_location("_authz_jwt", _JWT_PATH)
+_jwt = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(_jwt)
+
+
+def build_token(secret: str, *, issuer: str, audience: str, sub: str, client_id: str,
+                scope: str, actor: str, ttl: int) -> str:
+    now = int(time.time())
+    claims = {
+        "iss": issuer,
+        "sub": sub,
+        "client_id": client_id,
+        "scope": scope,
+        "iat": now,
+        "exp": now + ttl,
+    }
+    if audience:
+        claims["aud"] = audience
+    if actor:
+        claims["act"] = actor
+    return _jwt.encode(claims, secret)
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="离线签发鉴权探针令牌（HS256）")
+    ap.add_argument("--secret", required=True, help="签名密钥（须与运行时 MCP_AUTH_JWT_SECRET 一致）")
+    ap.add_argument("--issuer", default="https://auth.example.com", help="签发者 iss")
+    ap.add_argument("--aud", default="https://agentarts.example.com",
+                    help="受众 aud（用户令牌通常为 AgentArts 网关标识）")
+    ap.add_argument("--sub", default="user-alice", help="主体标识")
+    ap.add_argument("--client-id", default="agentarts-gateway", help="客户端标识")
+    ap.add_argument("--scope", default="demo:read demo:write", help='作用域，如 "demo:read demo:write"')
+    ap.add_argument("--actor", default="", help="委托方 act（token_exchange 委派令牌才需要）")
+    ap.add_argument("--ttl", type=int, default=3600, help="有效期（秒），默认 3600")
+    ap.add_argument("--env-json", action="store_true", help="以 JSON 打印可粘贴的 env 片段")
+    args = ap.parse_args()
+
+    token = build_token(
+        args.secret, issuer=args.issuer, audience=args.aud, sub=args.sub,
+        client_id=args.client_id, scope=args.scope, actor=args.actor, ttl=args.ttl,
+    )
+
+    if args.env_json:
+        print(json.dumps(
+            {"MCP_INBOUND_TOKEN": token, "MCP_AUTH_JWT_SECRET": args.secret,
+             "MCP_AUTH_ISSUER": args.issuer, "MCP_AUTH_AUDIENCE": args.aud},
+            ensure_ascii=False, indent=2,
+        ))
+    else:
+        print(token)
+
+
+if __name__ == "__main__":
+    main()

mcp_test_authz-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-test-authz"
+version = "0.1.0"
+description = "Authz probe MCP server (stdio) covering L2/L3 auth modes"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "mcp>=2.0.0",
+]
+
+[project.scripts]
+mcp-test-authz = "mcp_authz.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_authz"]

mcp_test_authz-0.1.0/src/mcp_authz/__init__.py

@@ -0,0 +1,3 @@
+from .server import mcp
+
+__all__ = ["mcp"]

mcp_test_authz-0.1.0/src/mcp_authz/_jwt.py

@@ -0,0 +1,81 @@
+"""极简 HS256 JWT 编解码（仅标准库）。
+
+本模块只做一件事：把「离线签发」与「本地校验」令牌所需的 HMAC-SHA256
+逻辑收敛到一处，且**不依赖 mcp / 任何第三方库**，便于单测与复用。
+
+生产建议：用 PyJWT，或改用非对称签名（RS256/ES256），资源侧只持有公钥。
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+
+
+class JWTError(ValueError):
+    """令牌编解码或校验失败。"""
+
+
+def _b64url_encode(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def _b64url_decode(seg: str) -> bytes:
+    pad = "=" * (-len(seg) % 4)
+    return base64.urlsafe_b64decode(seg + pad)
+
+
+def _sign(signing_input: bytes, secret: str) -> str:
+    digest = hmac.new(secret.encode("utf-8"), signing_input, hashlib.sha256).digest()
+    return _b64url_encode(digest)
+
+
+def encode(claims: dict, secret: str) -> str:
+    """用 HS256 把声明签发成 JWT。"""
+    header = {"alg": "HS256", "typ": "JWT"}
+    h = _b64url_encode(json.dumps(header, separators=(",", ":")).encode("utf-8"))
+    p = _b64url_encode(json.dumps(claims, separators=(",", ":")).encode("utf-8"))
+    return f"{h}.{p}.{_sign(f'{h}.{p}'.encode('ascii'), secret)}"
+
+
+def decode(
+    token: str,
+    secret: str,
+    *,
+    issuer: str | None = None,
+    audience: str | None = None,
+    leeway: int = 0,
+) -> dict:
+    """校验 JWT 并返回声明；任一校验不通过都抛 JWTError。"""
+    parts = (token or "").split(".")
+    if len(parts) != 3:
+        raise JWTError("令牌格式不合法（应为 header.payload.signature）")
+    header_seg, payload_seg, sig_seg = parts
+    try:
+        header = json.loads(_b64url_decode(header_seg))
+        claims = json.loads(_b64url_decode(payload_seg))
+    except Exception as exc:  # noqa: BLE001 - 解码失败统一转成 JWTError
+        raise JWTError(f"令牌解码失败：{exc}") from exc
+    if header.get("alg") != "HS256":
+        raise JWTError(f"不支持的签名算法：{header.get('alg')}")
+    if not hmac.compare_digest(_sign(f"{header_seg}.{payload_seg}".encode("ascii"), secret), sig_seg):
+        raise JWTError("令牌签名校验失败")
+
+    now = int(time.time())
+    exp = claims.get("exp")
+    if exp is not None and now > int(exp) + leeway:
+        raise JWTError("令牌已过期")
+    nbf = claims.get("nbf")
+    if nbf is not None and now + leeway < int(nbf):
+        raise JWTError("令牌尚未生效（nbf）")
+    if issuer is not None and claims.get("iss") != issuer:
+        raise JWTError(f"签发者不匹配：期望 {issuer}，实际 {claims.get('iss')}")
+    if audience is not None:
+        aud = claims.get("aud")
+        aud_list = aud if isinstance(aud, list) else [aud]
+        if audience not in aud_list:
+            raise JWTError(f"受众不匹配：令牌 aud={aud}，期望包含 {audience}")
+    return claims

mcp_test_authz-0.1.0/src/mcp_authz/server.py

@@ -0,0 +1,391 @@
+"""鉴权探针（Stdio / UVX）—— 与 HTTP 版同构，覆盖 L1 / L2 / L3 三层鉴权
+
+定位（与 HTTP 版的差异）
+------------------------
+HTTP 版通过**请求头**承载 L2 凭证，并按请求做中间件校验；Stdio 版没有入站 HTTP 传输
+（平台用 `uvx` 拉起本进程，经 stdin/stdout 通信），因此：
+
+- **L2 令牌经环境变量注入**：平台在 MCP 配置的 `env` 里下发令牌（`MCP_INBOUND_TOKEN`），
+  本服务在进程内本地校验（HS256 + iss/aud），并按模式 `MCP_AUTH_MODE` 分支；
+- **没有 `Authorization` 头冲突**：Stdio 不与平台走 HTTP，天然规避 1.4 所述的头名冲突；
+- **L3 完全同构**：本服务仍按 `UPSTREAM_AUTH_MODE` 用**自己的**凭证访问上游。
+
+工具与 HTTP 版保持一致，便于对照测试：
+    whoami（回显 L2 身份） / auth_matrix（回显生效配置） / call_upstream（验证 L3 凭证）。
+
+环境变量（AgentArts Stdio 模式在配置的 `env` 中注入，不要写进代码/镜像）
+------------------------------------------------------------------------
+L2：
+- `MCP_AUTH_MODE`      : none | apikey | jwt，默认 none
+- `MCP_INBOUND_TOKEN`  : 注入的入站凭证（jwt 模式为访问令牌；apikey 模式为被校验值）
+- `MCP_INBOUND_APIKEY` : apikey 模式下的期望 Key（与上面比对）
+- `MCP_AUTH_JWT_SECRET`: jwt 模式下的 HS256 验签密钥，缺失则 fail-closed
+- `MCP_AUTH_ISSUER`    : jwt 模式下期望的签发者 iss（可选，配置后强制校验）
+- `MCP_AUTH_AUDIENCE`  : jwt 模式下期望的受众 aud（可选，配置后强制校验）
+L3：
+- `UPSTREAM_AUTH_MODE` : static | client_credentials | token_exchange，默认 static
+- `UPSTREAM_URL`       : 上游基址，默认 http://127.0.0.1:9100
+- `UPSTREAM_API_KEY`   : static 模式下本服务访问上游的静态 Key
+- `AS_TOKEN_URL`       : 授权服务器令牌端点，默认 http://127.0.0.1:9000/token
+- `OAUTH_CLIENT_ID`    : 本服务的 OAuth client_id
+- `OAUTH_CLIENT_SECRET`: 本服务的 OAuth client_secret
+- `OAUTH_SCOPE`        : 申请的 scope，默认 "demo:read demo:write"
+- `OAUTH_ACTOR`        : token_exchange 委派令牌中的 act（本服务身份）
+- `OAUTH_AUDIENCE`     : token_exchange 的 audience（上游资源标识）
+"""
+
+from __future__ import annotations
+
+import functools
+import hmac
+import json
+import logging
+import os
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from mcp.server import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+
+from . import _jwt
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("authz-mcp-stdio")
+
+# 创建 MCP 服务器实例 (v2: MCPServer)
+mcp = MCPServer("authz-mcp-server")
+
+# --------------------------------------------------------------------------- #
+# 配置
+# --------------------------------------------------------------------------- #
+MCP_AUTH_MODE_ENV = "MCP_AUTH_MODE"
+MCP_INBOUND_TOKEN_ENV = "MCP_INBOUND_TOKEN"
+MCP_INBOUND_APIKEY_ENV = "MCP_INBOUND_APIKEY"
+MCP_AUTH_JWT_SECRET_ENV = "MCP_AUTH_JWT_SECRET"
+MCP_AUTH_ISSUER_ENV = "MCP_AUTH_ISSUER"
+MCP_AUTH_AUDIENCE_ENV = "MCP_AUTH_AUDIENCE"
+
+UPSTREAM_AUTH_MODE_ENV = "UPSTREAM_AUTH_MODE"
+UPSTREAM_URL_ENV = "UPSTREAM_URL"
+UPSTREAM_API_KEY_ENV = "UPSTREAM_API_KEY"
+AS_TOKEN_URL_ENV = "AS_TOKEN_URL"
+OAUTH_CLIENT_ID_ENV = "OAUTH_CLIENT_ID"
+OAUTH_CLIENT_SECRET_ENV = "OAUTH_CLIENT_SECRET"
+OAUTH_SCOPE_ENV = "OAUTH_SCOPE"
+OAUTH_ACTOR_ENV = "OAUTH_ACTOR"
+OAUTH_AUDIENCE_ENV = "OAUTH_AUDIENCE"
+
+DEFAULT_MCP_AUTH_MODE = "none"
+DEFAULT_UPSTREAM_AUTH_MODE = "static"
+DEFAULT_UPSTREAM_URL = "http://127.0.0.1:9100"
+DEFAULT_AS_TOKEN_URL = "http://127.0.0.1:9000/token"
+DEFAULT_CLIENT_ID = "authz-mcp-client"
+DEFAULT_CLIENT_SECRET = "authz-mcp-secret"
+DEFAULT_SCOPE = "demo:read demo:write"
+DEFAULT_ACTOR = "service:authz-mcp"
+DEFAULT_AUDIENCE = "https://upstream.demo.example.com"
+
+# RFC 8693 常量
+TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange"
+ACCESS_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token"
+
+
+def _env(name: str, default: str = "") -> str:
+    return os.getenv(name, default).strip()
+
+
+def _mcp_auth_mode() -> str:
+    return _env(MCP_AUTH_MODE_ENV, DEFAULT_MCP_AUTH_MODE).lower()
+
+
+def _upstream_auth_mode() -> str:
+    return _env(UPSTREAM_AUTH_MODE_ENV, DEFAULT_UPSTREAM_AUTH_MODE).lower()
+
+
+def _upstream_url() -> str:
+    return _env(UPSTREAM_URL_ENV, DEFAULT_UPSTREAM_URL)
+
+
+def _token_url() -> str:
+    return _env(AS_TOKEN_URL_ENV, DEFAULT_AS_TOKEN_URL)
+
+
+def _client_id() -> str:
+    return _env(OAUTH_CLIENT_ID_ENV, DEFAULT_CLIENT_ID)
+
+
+def _client_secret() -> str:
+    return _env(OAUTH_CLIENT_SECRET_ENV, DEFAULT_CLIENT_SECRET)
+
+
+def _scope() -> str:
+    return _env(OAUTH_SCOPE_ENV, DEFAULT_SCOPE)
+
+
+def _actor() -> str:
+    return _env(OAUTH_ACTOR_ENV, DEFAULT_ACTOR)
+
+
+def _audience() -> str:
+    return _env(OAUTH_AUDIENCE_ENV, DEFAULT_AUDIENCE)
+
+
+def _mask(token: str | None) -> str:
+    if not token:
+        return ""
+    if len(token) <= 16:
+        return "*" * len(token)
+    return f"{token[:8]}...{token[-6:]}（已脱敏）"
+
+
+def _surface_errors(fn):
+    """兜底装饰器：把工具内未预期的异常转成 ToolError，让失败原因对模型可见。"""
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except ToolError:
+            raise
+        except Exception as exc:  # noqa: BLE001 - 故意兜底，确保错误可见
+            logger.exception("工具 %s 执行异常", fn.__name__)
+            raise ToolError(f"{fn.__name__} 执行失败：{type(exc).__name__}: {exc}") from exc
+
+    return wrapper
+
+
+# --------------------------------------------------------------------------- #
+# L2：进程内本地校验（none / apikey / jwt）
+# --------------------------------------------------------------------------- #
+def _l2_inbound() -> dict:
+    """按 `MCP_AUTH_MODE` 校验 env 注入的入站凭证，返回上下文；失败一律抛 ToolError。"""
+    mode = _mcp_auth_mode()
+    if mode == "none":
+        return {"mode": "none"}
+
+    if mode == "apikey":
+        expected = _env(MCP_INBOUND_APIKEY_ENV)
+        if not expected:
+            raise ToolError(f"MCP_AUTH_MODE=apikey 但未配置 {MCP_INBOUND_APIKEY_ENV}（fail-closed）")
+        presented = _env(MCP_INBOUND_TOKEN_ENV)
+        if not hmac.compare_digest(presented, expected):
+            raise ToolError(f"入站 API Key 缺失或不正确：请在 env 注入 {MCP_INBOUND_TOKEN_ENV}")
+        return {"mode": "apikey", "credential": presented}
+
+    if mode == "jwt":
+        token = _env(MCP_INBOUND_TOKEN_ENV)
+        if not token:
+            raise ToolError(f"鉴权失败：未配置 {MCP_INBOUND_TOKEN_ENV}（入站访问令牌），请在 env 注入。")
+        secret = _env(MCP_AUTH_JWT_SECRET_ENV)
+        if not secret:
+            raise ToolError(f"鉴权失败：未配置 {MCP_AUTH_JWT_SECRET_ENV}（验签密钥），fail-closed。")
+        try:
+            claims = _jwt.decode(
+                token, secret,
+                issuer=_env(MCP_AUTH_ISSUER_ENV) or None,
+                audience=_env(MCP_AUTH_AUDIENCE_ENV) or None,
+            )
+        except _jwt.JWTError as exc:
+            raise ToolError(f"令牌校验失败：{exc}") from exc
+        return {"mode": "jwt", "credential": token, "token": token, "claims": claims}
+
+    raise ToolError(f"未知的 MCP_AUTH_MODE：{mode}")
+
+
+def _subject_token() -> str:
+    """取得 L2 注入的用户令牌（供 token_exchange 使用）。"""
+    return _env(MCP_INBOUND_TOKEN_ENV)
+
+
+# --------------------------------------------------------------------------- #
+# L3：取上游凭证 —— static / client_credentials / token_exchange 三种模式
+# --------------------------------------------------------------------------- #
+_TOKEN_LOCK = threading.Lock()
+_TOKEN_CACHE: dict = {"token": None, "exp": 0.0, "subject": None}
+
+
+def _as_post(form: dict) -> dict:
+    data = urllib.parse.urlencode(form).encode("utf-8")
+    req = urllib.request.Request(
+        _token_url(), data=data, method="POST",
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", "ignore")
+        raise ToolError(f"向授权服务器取令牌失败：HTTP {exc.code} {detail}") from exc
+    except ToolError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise ToolError(f"向授权服务器取令牌失败：{type(exc).__name__}: {exc}") from exc
+
+
+def _fetch_service_token(force: bool = False) -> str:
+    """client_credentials：用本服务自己的 client_id/secret 取令牌（带缓存/自动刷新）。"""
+    with _TOKEN_LOCK:
+        now = time.time()
+        if not force and _TOKEN_CACHE["token"] and _TOKEN_CACHE["exp"] - 30 > now:
+            return _TOKEN_CACHE["token"]
+        payload = _as_post({
+            "grant_type": "client_credentials",
+            "client_id": _client_id(),
+            "client_secret": _client_secret(),
+            "scope": _scope(),
+        })
+        token = payload.get("access_token")
+        if not token:
+            raise ToolError(f"授权服务器未返回 access_token：{payload}")
+        _TOKEN_CACHE.update({"token": token, "exp": now + float(payload.get("expires_in", 3600))})
+        logger.info("已取得服务令牌：client_id=%s scope=%s", _client_id(), payload.get("scope"))
+        return token
+
+
+def _exchange_token(subject_token: str, force: bool = False) -> str:
+    """token_exchange（RFC 8693）：用入站用户令牌换取委派令牌（带缓存/自动刷新）。"""
+    with _TOKEN_LOCK:
+        now = time.time()
+        if (
+            not force
+            and _TOKEN_CACHE["token"]
+            and _TOKEN_CACHE["subject"] == subject_token
+            and _TOKEN_CACHE["exp"] - 30 > now
+        ):
+            return _TOKEN_CACHE["token"]
+        payload = _as_post({
+            "grant_type": TOKEN_EXCHANGE_GRANT,
+            "client_id": _client_id(),
+            "client_secret": _client_secret(),
+            "subject_token": subject_token,
+            "subject_token_type": ACCESS_TOKEN_TYPE,
+            "audience": _audience(),
+            "scope": _scope(),
+        })
+        token = payload.get("access_token")
+        if not token:
+            raise ToolError(f"授权服务器未返回 access_token：{payload}")
+        _TOKEN_CACHE.update({
+            "token": token, "exp": now + float(payload.get("expires_in", 3600)), "subject": subject_token,
+        })
+        return token
+
+
+def _l3_headers() -> tuple[dict, str]:
+    """按 `UPSTREAM_AUTH_MODE` 生成访问上游所需请求头，返回 (headers, 使用的模式)。"""
+    mode = _upstream_auth_mode()
+    if mode == "static":
+        key = _env(UPSTREAM_API_KEY_ENV)
+        if not key:
+            raise ToolError("UPSTREAM_AUTH_MODE=static 需要配置 UPSTREAM_API_KEY")
+        return {"X-Api-Key": key}, "static"
+    if mode == "client_credentials":
+        return {"Authorization": f"Bearer {_fetch_service_token()}"}, "client_credentials"
+    if mode == "token_exchange":
+        subject = _subject_token()
+        if not subject or _mcp_auth_mode() != "jwt":
+            raise ToolError(
+                "UPSTREAM_AUTH_MODE=token_exchange 需要 L2 提供用户令牌；"
+                "请将 MCP_AUTH_MODE 设为 jwt 并注入 MCP_INBOUND_TOKEN。"
+            )
+        return {"Authorization": f"Bearer {_exchange_token(subject)}"}, "token_exchange"
+    raise ToolError(f"未知的 UPSTREAM_AUTH_MODE：{mode}")
+
+
+# --------------------------------------------------------------------------- #
+# 工具（与 HTTP 版同名）
+# --------------------------------------------------------------------------- #
+@mcp.tool()
+@_surface_errors
+def whoami() -> dict:
+    """回显本次调用的 L2 身份信息（模式 / 令牌声明）。"""
+    inbound = _l2_inbound()
+    claims = inbound.get("claims") or {}
+    credential = inbound.get("credential", "")
+    return {
+        "l2_mode": inbound.get("mode", _mcp_auth_mode()),
+        "l2_source": MCP_INBOUND_TOKEN_ENV,
+        "credential_present": bool(credential),
+        "credential_preview": _mask(credential),
+        "inbound_claims": {
+            "sub": claims.get("sub"),
+            "iss": claims.get("iss"),
+            "aud": claims.get("aud"),
+            "client_id": claims.get("client_id"),
+            "scope": claims.get("scope"),
+            "act": claims.get("act"),
+            "exp": claims.get("exp"),
+        },
+    }
+
+
+@mcp.tool()
+@_surface_errors
+def auth_matrix() -> dict:
+    """回显本服务当前生效的鉴权配置（L2 / L3 全量），用于快速核对 env 是否注入正确。"""
+    return {
+        "l2": {
+            "mode": _mcp_auth_mode(),
+            "token_env": MCP_INBOUND_TOKEN_ENV,
+            "token_configured": bool(_env(MCP_INBOUND_TOKEN_ENV)),
+            "apikey_configured": bool(_env(MCP_INBOUND_APIKEY_ENV)),
+            "jwt_secret_configured": bool(_env(MCP_AUTH_JWT_SECRET_ENV)),
+            "issuer": _env(MCP_AUTH_ISSUER_ENV) or None,
+            "audience": _env(MCP_AUTH_AUDIENCE_ENV) or None,
+        },
+        "l3": {
+            "mode": _upstream_auth_mode(),
+            "upstream_url": _upstream_url(),
+            "static_key_configured": bool(_env(UPSTREAM_API_KEY_ENV)),
+            "as_token_url": _token_url(),
+            "client_id": _client_id(),
+            "scope": _scope(),
+            "actor": _actor(),
+            "audience": _audience(),
+        },
+        "notes": {
+            "token_passthrough": False,
+            "l2_transport": "stdio: 平台在 env 注入令牌，进程内本地校验（无 HTTP 头冲突）",
+            "l1": "运行时端点鉴权由 AgentArts 网关负责，与本服务代码无关",
+        },
+    }
+
+
+@mcp.tool()
+@_surface_errors
+def call_upstream(path: str = "/echo") -> dict:
+    """按 L3 模式取得凭证并调用上游，回显上游的鉴权结果（sub / act / scope / via）。
+
+    token_exchange 模式需搭配 L2 的 jwt 模式使用。
+
+    Args:
+        path: 上游路径，默认 /echo。
+    """
+    headers, via = _l3_headers()
+    req = urllib.request.Request(
+        _upstream_url().rstrip("/") + path, method="GET",
+        headers={**headers, "Accept": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            payload = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", "ignore")
+        raise ToolError(f"调用上游失败：HTTP {exc.code} {detail}") from exc
+    except ToolError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise ToolError(f"调用上游失败：{type(exc).__name__}: {exc}") from exc
+    return {"l3_mode": via, "upstream_url": _upstream_url(), "upstream": payload}
+
+
+def main() -> None:
+    """UVX 入口点 — 以 stdio 模式启动 MCP 服务"""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()