tfrs-auth 0.1.0__tar.gz

tfrs_auth-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.whl
+
+# uv / venv
+.venv/
+venv/
+.uv/
+
+# 测试 / 覆盖
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# 环境与密钥（E2E 凭证绝不入库）
+.env
+.env.*
+!.env.example
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store

tfrs_auth-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TuringFocus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tfrs_auth-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: tfrs-auth
+Version: 0.1.0
+Summary: TFRS 跨语言共享凭证工具包（Python）：PAT/client_credentials → 短 JWT 换发 + 缓存/刷新 + 纯 RS256 验签
+Project-URL: Homepage, https://cnb.cool/turingfocus/foundation/tfrs-foundation-py
+Project-URL: Repository, https://cnb.cool/turingfocus/foundation/tfrs-foundation-py
+Project-URL: Issues, https://cnb.cool/turingfocus/foundation/tfrs-foundation-py/-/issues
+Author: TuringFocus
+License-Expression: MIT
+License-File: LICENSE
+Keywords: jwt,oauth,rfc8693,tfrs,token-exchange
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pyjwt[crypto]>=2.8
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.27; extra == 'httpx'
+Description-Content-Type: text/markdown
+
+# tfrs-auth (Python)
+
+TFRS AccessToken 客户端工具包：把「PAT / `client_credentials` → 短 RS256 JWT 换发
+（RFC 8693）+ 缓存/刷新」与「Claims/scope 契约 + 纯验签」抽成可复用包，避免每个
+MCP 工具 / SDK 重复实现 token 获取与生命周期管理。
+
+> SoT = TFRSManager Contract Registry。本包 `contract.py` 为镜像，**变更先改 Manager**。
+> 强制执行层（验签中间件/Socket.IO/ESO/默认拒绝 CI）**不在本包**，留 TFRobotServer。
+
+## 安装
+
+```bash
+# 从 PyPI（推荐）
+uv add tfrs-auth                  # 核心：契约 + 纯验签
+uv add "tfrs-auth[httpx]"         # 含客户端 token source / JWKS live 拉取
+# 或：pip install "tfrs-auth[httpx]"
+
+# 或从 git + tag（未发布版本）
+uv add "tfrs-auth[httpx] @ git+https://cnb.cool/turingfocus/foundation/tfrs-foundation-py@<tag>#subdirectory=packages/tfrs-auth"
+```
+
+- 核心依赖：`pyjwt[crypto]`（契约 + 纯验签）。
+- 可选 extra `httpx`：客户端 token source / JWKS live 拉取。
+- 许可证：MIT。
+
+## 用法
+
+### 客户端 token source（`client_credentials`，S5 A2A 主叫端）
+
+```python
+from tfrs_auth import AsyncCachingTokenSource, ClientCredentials
+
+cred = ClientCredentials.for_robot(
+    client_id=machine_client_id,          # 机器人自身 Account.ID
+    client_secret=machine_client_secret,  # tfp_ 明文（machineClientSecret）
+    callee_robot_id=callee_id,            # → aud=robot:<calleeId>
+    scope=["a2a:invoke"],
+)
+async with AsyncCachingTokenSource(
+    cred, token_url="https://<user-host>/api/v1/oauth/token"
+) as source:
+    token = await source.token()          # 缓存 + 临期自动刷新 + 退避
+    headers = {"Authorization": f"Bearer {token.access_token}"}
+```
+
+同步场景用 `CachingTokenSource`（API 对称）。
+
+### 纯验签（资源服务器侧，零网络）
+
+```python
+from tfrs_auth import JwtVerifier
+
+verifier = JwtVerifier.from_jwks(jwks_dict, issuer="https://<user-host>", audience="robot:42")
+claims = verifier.verify(access_token)    # 失败抛 TokenVerificationError
+assert claims.has_scope("a2a:invoke")
+```
+
+live 拉取 JWKS：`JwtVerifier.from_url("https://<user-host>/.well-known/jwks.json", ...)`。
+
+> ⚠️ **资源服务器务必传 `issuer` 与 `audience`**：二者仅在提供时才校验。不传 `audience`
+> 会放行签给**任意**机器人的 token，丧失 `aud=robot:<id>` 受众隔离（`issuer` 之于颁发者
+> 隔离同理）。`from_url` 的未知-kid 刷新已内置限速（`min_refresh_interval`，默认 10s），
+> 避免被构造的随机-kid token 放大成对 JWKS 端点的 DoS。
+>
+> 异常约定：验签失败抛 `TokenVerificationError`；`from_url` 模式下 JWKS 拉取的网络失败抛
+> `TransportError`。消费方应 `except (TokenVerificationError, TransportError)` 同时兜住。
+
+## 模块
+
+| 模块 | 内容 |
+|------|------|
+| `contract` | `Scope`(8 active + 2 reserved) · `Claims` · `GrantType`/`SubjectTokenType` URN · `OAuthErrorCode` · JWKS/kid 形状 |
+| `errors` | 异常树（`InvalidClientError`(401) / `InvalidTargetError` / `TemporarilyUnavailableError`(503) …）+ `from_oauth_error` |
+| `client` | `Token` · `TokenSource`/`AsyncTokenSource` · `CachingTokenSource` / `AsyncCachingTokenSource`（single-flight + 退避）|
+| `credentials` | `ClientCredentials`（✅）· `PatCredential` / `UserJwtCredential`（骨架）|
+| `verify` | `JwtVerifier`（RS256 + JWKS）|
+| `transport` | `BearerAuth`（httpx auth，骨架）|
+
+## 边界与状态
+
+- **已实现**：`contract` / `errors` / `client`(sync+async caching) / `credentials.ClientCredentials` / `verify`。
+- **骨架（首批 CNB Issue）**：`credentials.PatCredential` / `credentials.UserJwtCredential` / `transport.BearerAuth`。

tfrs_auth-0.1.0/README.md

@@ -0,0 +1,82 @@
+# tfrs-auth (Python)
+
+TFRS AccessToken 客户端工具包：把「PAT / `client_credentials` → 短 RS256 JWT 换发
+（RFC 8693）+ 缓存/刷新」与「Claims/scope 契约 + 纯验签」抽成可复用包，避免每个
+MCP 工具 / SDK 重复实现 token 获取与生命周期管理。
+
+> SoT = TFRSManager Contract Registry。本包 `contract.py` 为镜像，**变更先改 Manager**。
+> 强制执行层（验签中间件/Socket.IO/ESO/默认拒绝 CI）**不在本包**，留 TFRobotServer。
+
+## 安装
+
+```bash
+# 从 PyPI（推荐）
+uv add tfrs-auth                  # 核心：契约 + 纯验签
+uv add "tfrs-auth[httpx]"         # 含客户端 token source / JWKS live 拉取
+# 或：pip install "tfrs-auth[httpx]"
+
+# 或从 git + tag（未发布版本）
+uv add "tfrs-auth[httpx] @ git+https://cnb.cool/turingfocus/foundation/tfrs-foundation-py@<tag>#subdirectory=packages/tfrs-auth"
+```
+
+- 核心依赖：`pyjwt[crypto]`（契约 + 纯验签）。
+- 可选 extra `httpx`：客户端 token source / JWKS live 拉取。
+- 许可证：MIT。
+
+## 用法
+
+### 客户端 token source（`client_credentials`，S5 A2A 主叫端）
+
+```python
+from tfrs_auth import AsyncCachingTokenSource, ClientCredentials
+
+cred = ClientCredentials.for_robot(
+    client_id=machine_client_id,          # 机器人自身 Account.ID
+    client_secret=machine_client_secret,  # tfp_ 明文（machineClientSecret）
+    callee_robot_id=callee_id,            # → aud=robot:<calleeId>
+    scope=["a2a:invoke"],
+)
+async with AsyncCachingTokenSource(
+    cred, token_url="https://<user-host>/api/v1/oauth/token"
+) as source:
+    token = await source.token()          # 缓存 + 临期自动刷新 + 退避
+    headers = {"Authorization": f"Bearer {token.access_token}"}
+```
+
+同步场景用 `CachingTokenSource`（API 对称）。
+
+### 纯验签（资源服务器侧，零网络）
+
+```python
+from tfrs_auth import JwtVerifier
+
+verifier = JwtVerifier.from_jwks(jwks_dict, issuer="https://<user-host>", audience="robot:42")
+claims = verifier.verify(access_token)    # 失败抛 TokenVerificationError
+assert claims.has_scope("a2a:invoke")
+```
+
+live 拉取 JWKS：`JwtVerifier.from_url("https://<user-host>/.well-known/jwks.json", ...)`。
+
+> ⚠️ **资源服务器务必传 `issuer` 与 `audience`**：二者仅在提供时才校验。不传 `audience`
+> 会放行签给**任意**机器人的 token，丧失 `aud=robot:<id>` 受众隔离（`issuer` 之于颁发者
+> 隔离同理）。`from_url` 的未知-kid 刷新已内置限速（`min_refresh_interval`，默认 10s），
+> 避免被构造的随机-kid token 放大成对 JWKS 端点的 DoS。
+>
+> 异常约定：验签失败抛 `TokenVerificationError`；`from_url` 模式下 JWKS 拉取的网络失败抛
+> `TransportError`。消费方应 `except (TokenVerificationError, TransportError)` 同时兜住。
+
+## 模块
+
+| 模块 | 内容 |
+|------|------|
+| `contract` | `Scope`(8 active + 2 reserved) · `Claims` · `GrantType`/`SubjectTokenType` URN · `OAuthErrorCode` · JWKS/kid 形状 |
+| `errors` | 异常树（`InvalidClientError`(401) / `InvalidTargetError` / `TemporarilyUnavailableError`(503) …）+ `from_oauth_error` |
+| `client` | `Token` · `TokenSource`/`AsyncTokenSource` · `CachingTokenSource` / `AsyncCachingTokenSource`（single-flight + 退避）|
+| `credentials` | `ClientCredentials`（✅）· `PatCredential` / `UserJwtCredential`（骨架）|
+| `verify` | `JwtVerifier`（RS256 + JWKS）|
+| `transport` | `BearerAuth`（httpx auth，骨架）|
+
+## 边界与状态
+
+- **已实现**：`contract` / `errors` / `client`(sync+async caching) / `credentials.ClientCredentials` / `verify`。
+- **骨架（首批 CNB Issue）**：`credentials.PatCredential` / `credentials.UserJwtCredential` / `transport.BearerAuth`。

tfrs_auth-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "tfrs-auth"
+version = "0.1.0"
+description = "TFRS 跨语言共享凭证工具包（Python）：PAT/client_credentials → 短 JWT 换发 + 缓存/刷新 + 纯 RS256 验签"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "TuringFocus" }]
+keywords = ["oauth", "rfc8693", "token-exchange", "jwt", "tfrs"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    # 纯验签（verify.from_jwks）+ 契约只需 pyjwt[crypto]；httpx 为可选 extra。
+    "pyjwt[crypto]>=2.8",
+]
+
+[project.optional-dependencies]
+# 客户端 token source / JWKS live 拉取需要 httpx。
+httpx = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://cnb.cool/turingfocus/foundation/tfrs-foundation-py"
+Repository = "https://cnb.cool/turingfocus/foundation/tfrs-foundation-py"
+Issues = "https://cnb.cool/turingfocus/foundation/tfrs-foundation-py/-/issues"
+
+[build-system]
+# hatchling >= 1.27 才支持 PEP 639 的 SPDX license 表达式（license = "MIT"）。
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tfrs_auth"]

tfrs_auth-0.1.0/src/tfrs_auth/__init__.py

@@ -0,0 +1,116 @@
+"""tfrs-auth —— TFRS 跨语言共享凭证工具包（Python）。
+
+三层（PRD §13.2，**强制执行层不进包**，留 TFRobotServer）：
+
+1. **契约层** :mod:`tfrs_auth.contract` —— Claims / scope 词表 / 错误码 / grant·
+   token-type URN / JWKS·kid 形状（M0 SoT 镜像）。
+2. **客户端 token source** :mod:`tfrs_auth.client` + :mod:`tfrs_auth.credentials`
+   —— PAT / User JWT / client_credentials 换发 + 缓存 / single-flight 刷新 / 退避。
+3. **纯验签** :mod:`tfrs_auth.verify` —— RS256 + JWKS，零 Web 框架。
+
+快速上手（client_credentials，S5 A2A 主叫端）::
+
+    from tfrs_auth import AsyncCachingTokenSource, ClientCredentials, JwtVerifier
+
+    cred = ClientCredentials.for_robot(
+        client_id=machine_client_id,
+        client_secret=machine_client_secret,
+        callee_robot_id=callee_id,
+        scope=["a2a:invoke"],
+    )
+    source = AsyncCachingTokenSource(cred, token_url="https://<host>/api/v1/oauth/token")
+    token = await source.token()            # 缓存 + 临期自动刷新
+    # 注入：Authorization: Bearer {token.access_token}
+"""
+
+from __future__ import annotations
+
+from . import contract, credentials, verify
+from .client import (
+    AsyncCachingTokenSource,
+    AsyncTokenSource,
+    CachingTokenSource,
+    Credential,
+    Token,
+    TokenSource,
+)
+from .contract import (
+    ACTIVE_SCOPES,
+    CONTRACT_VERSION,
+    DEFAULT_KID,
+    RESERVED_SCOPES,
+    SIGNING_ALG,
+    Claims,
+    GrantType,
+    OAuthErrorCode,
+    Scope,
+    SubjectTokenType,
+    is_active_scope,
+    robot_audience,
+    scopes_from_str,
+    scopes_to_str,
+)
+from .credentials import ClientCredentials, PatCredential, UserJwtCredential
+from .errors import (
+    InvalidClientError,
+    InvalidGrantError,
+    InvalidRequestError,
+    InvalidScopeError,
+    InvalidTargetError,
+    PaymentRequiredError,
+    TemporarilyUnavailableError,
+    TfrsAuthError,
+    TokenExchangeError,
+    TokenVerificationError,
+    TransportError,
+)
+from .verify import JwtVerifier
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # 子模块
+    "contract",
+    "credentials",
+    "verify",
+    # 契约
+    "Claims",
+    "Scope",
+    "GrantType",
+    "SubjectTokenType",
+    "OAuthErrorCode",
+    "ACTIVE_SCOPES",
+    "RESERVED_SCOPES",
+    "CONTRACT_VERSION",
+    "DEFAULT_KID",
+    "SIGNING_ALG",
+    "is_active_scope",
+    "scopes_to_str",
+    "scopes_from_str",
+    "robot_audience",
+    # 客户端
+    "Token",
+    "TokenSource",
+    "AsyncTokenSource",
+    "Credential",
+    "CachingTokenSource",
+    "AsyncCachingTokenSource",
+    "ClientCredentials",
+    "PatCredential",
+    "UserJwtCredential",
+    # 验签
+    "JwtVerifier",
+    # 错误
+    "TfrsAuthError",
+    "TokenExchangeError",
+    "TokenVerificationError",
+    "TransportError",
+    "InvalidClientError",
+    "InvalidGrantError",
+    "InvalidRequestError",
+    "InvalidTargetError",
+    "InvalidScopeError",
+    "TemporarilyUnavailableError",
+    "PaymentRequiredError",
+]