theseus-kit 0.1.0__py3-none-any.whl

theseus_kit/__init__.py

@@ -0,0 +1,126 @@
+"""theseus-kit MCP server."""
+
+from theseus_kit.config import (
+    CredentialConfig,
+    OAuthConfig,
+    RobotTarget,
+    TheseusSettings,
+    UserPatConfig,
+)
+from theseus_kit.errors import (
+    AuthRejectedError,
+    ConfigError,
+    ConfigLocatorError,
+    CredentialError,
+    DraftConflictError,
+    DraftNotFoundError,
+    ExchangeUnavailableError,
+    LlmsDocError,
+    PublishNotConfirmedError,
+    PublishPreCheckError,
+    RobotApiError,
+    RobotValidationError,
+    RoutingConfigError,
+    ScopeOrAudienceError,
+    SubscriptionFrozenError,
+    TheseusError,
+)
+from theseus_kit.models import (
+    ConfigDetail,
+    ConfigSummary,
+    CreateDraftResponse,
+    CursorData,
+    DraftTopology,
+    DraftValidateResponse,
+    DraftValidationErrorItem,
+    DraftValidationResult,
+    ListNode,
+    ListNodesResponse,
+    LlmsDoc,
+    NodeKind,
+    PaginatedList,
+    PublishConfigResponse,
+    SaveTemplateResponse,
+    StateSummary,
+    TemplateResponse,
+    TFSResponse,
+    TopologyNode,
+    UpdateDraftResponse,
+    compute_config_hash,
+)
+from theseus_kit.oauth import TheseusTokenVerifier, build_token_verifier
+from theseus_kit.resources import set_last_locator
+from theseus_kit.routing import RequestContext
+from theseus_kit.server import create_mcp_server
+from theseus_kit.services import (
+    ConfigPublisher,
+    ConfigReader,
+    DraftCreator,
+    DraftEditor,
+    DraftValidator,
+    LlmsDocReader,
+    TemplateSaver,
+)
+from theseus_kit.transport import RobotClient, StaticTokenSource
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "TheseusSettings",
+    "RobotTarget",
+    "CredentialConfig",
+    "OAuthConfig",
+    "UserPatConfig",
+    "RequestContext",
+    "RobotClient",
+    "StaticTokenSource",
+    "TheseusError",
+    "ConfigError",
+    "ConfigLocatorError",
+    "DraftConflictError",
+    "DraftNotFoundError",
+    "LlmsDocError",
+    "RoutingConfigError",
+    "CredentialError",
+    "ScopeOrAudienceError",
+    "SubscriptionFrozenError",
+    "ExchangeUnavailableError",
+    "AuthRejectedError",
+    "RobotApiError",
+    "RobotValidationError",
+    "TheseusTokenVerifier",
+    "build_token_verifier",
+    "create_mcp_server",
+    "ConfigReader",
+    "DraftEditor",
+    "LlmsDocReader",
+    "ConfigSummary",
+    "StateSummary",
+    "ListNodesResponse",
+    "LlmsDoc",
+    "ListNode",
+    "NodeKind",
+    "ConfigDetail",
+    "CreateDraftResponse",
+    "DraftTopology",
+    "DraftValidateResponse",
+    "DraftValidationErrorItem",
+    "DraftValidationResult",
+    "TemplateResponse",
+    "TopologyNode",
+    "CursorData",
+    "TFSResponse",
+    "PaginatedList",
+    "UpdateDraftResponse",
+    "PublishConfigResponse",
+    "SaveTemplateResponse",
+    "compute_config_hash",
+    "ConfigPublisher",
+    "DraftCreator",
+    "DraftValidator",
+    "TemplateSaver",
+    "PublishNotConfirmedError",
+    "PublishPreCheckError",
+    "set_last_locator",
+]

theseus_kit/__main__.py

@@ -0,0 +1,4 @@
+from theseus_kit.server import main
+
+if __name__ == "__main__":
+    main()

theseus_kit/config.py

@@ -0,0 +1,155 @@
+"""Configuration: robot routing target + credential, loaded from env or a file.
+
+Routing metadata is **explicit** (config-injected), never discovered from
+Manager — editing a specific robot inherently requires declaring which one, and
+embedded/internal deployments inject these values externally.
+
+Credentials default to ``user_pat`` — the user's personal access token is
+exchanged for a robot-scoped JWT via Manager's token-exchange endpoint.
+All secret fields are pydantic ``SecretStr`` so default ``repr`` / logs never expose
+them.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class RobotTarget(BaseModel):
+    """One target robot's routing identity + endpoints + TLS.
+
+    None of these is the token ``audience``: the ``audience`` is a credential
+    concern (``robot:{public_id}``) derived from the credential config. The
+    ``rid`` here is the ``X-TF-RobotId`` value — a different identifier.
+    """
+
+    robot_id: str = Field(description="rid → X-TF-RobotId 与集群内路由（≠ public_id）")
+    namespace: str = Field(description="租户 K8s Namespace → X-TF-Namespace")
+    robot_type: str = Field(description="机器人类型（如 tfrobot / openclaw）→ X-TF-RobotType")
+    api_base_url: str = Field(description="机器人 HTTP 入口 https://api.<clusterDomain>")
+    manager_base_url: str = Field(description="TFRSManager 公共入口（POST /api/v1/oauth/token 的 host）")
+    verify: bool = Field(default=True, description="HTTPS 证书校验")
+    ca_bundle: Path | None = Field(default=None, description="自定义 CA bundle（自签 / 本地开发兜底）")
+    timeout_s: float = Field(default=30.0, ge=1.0, description="HTTP 超时（秒）")
+
+    @field_validator("api_base_url", "manager_base_url")
+    @classmethod
+    def _validate_url_scheme(cls, value: str) -> str:
+        if not value.startswith(("http://", "https://")):
+            raise ValueError(f"URL must start with http:// or https://; got {value!r}")
+        return value
+
+    @field_validator("ca_bundle")
+    @classmethod
+    def _validate_ca_bundle(cls, value: Path | None) -> Path | None:
+        if value is not None and not value.is_file():
+            raise ValueError(f"ca_bundle file not found: {value}")
+        return value
+
+
+class UserPatConfig(BaseModel):
+    """User personal access token (direct-user / future-OAuth path).
+
+    A user PAT can target any of the user's robots, so the target robot's
+    ``public_id`` (``{orgSlug}:{employeeNo}``) must be named explicitly as the
+    token ``audience``.
+    """
+
+    kind: Literal["user_pat"] = "user_pat"
+    pat: SecretStr = Field(description="用户个人访问令牌（tfp_…）")
+    robot_public_id: str = Field(
+        description="目标机器人 public_id（{orgSlug}:{employeeNo}）→ audience robot:{public_id}",
+        pattern=r"^[a-z0-9-]+:[a-zA-Z0-9]+$",
+    )
+
+
+class OAuthConfig(BaseModel):
+    """OAuth 2.0 / 2.1 authorization (MCP-standard, no PAT).
+
+    When no explicit PAT is configured, theseus-kit
+    acts as an OAuth Protected Resource (RS): the MCP Client drives the
+    authorization-code + PKCE flow against the TFRSManager AS, and theseus-kit
+    validates the resulting Bearer token then forwards it directly to the target
+    TFRobotServer (no token exchange — TFRobotServer natively accepts OAuth AS
+    tokens per §10.1-new of the OAuth design).
+
+    .. seealso:: :ref:`docs/auth-oauth-design.md` §4, §5.
+    """
+
+    kind: Literal["oauth"] = "oauth"
+    authorization_server: str = Field(
+        description="TFRSManager OAuth AS base URL（用于 PRM 发现 + Bearer 校验的 JWKS 获取）",
+    )
+    scopes: str = Field(
+        default="config:read",
+        description="Space-separated scope string（与 PAT 路径默认值一致）",
+    )
+    client_id: str | None = Field(
+        default=None,
+        description="预注册 client_id；None 时走 DCR / CIMD（MCP SDK 处理）",
+    )
+    redirect_uri: str | None = Field(
+        default=None,
+        description="STDIO 外部回调 URI（Topology B）；Topology A（HTTP/MCP Client）不需要",
+    )
+    resource_server_url: str | None = Field(
+        default=None,
+        description=(
+            "theseus-kit PRM resource URL（Topology A HTTP 入口），"
+            "用作 token audience 校验 + AuthSettings.resource_server_url；"
+            "None 跳过 audience 校验（宽松模式，仅开发/调试）"
+        ),
+    )
+
+    @field_validator("authorization_server")
+    @classmethod
+    def _validate_authorization_server_url(cls, value: str) -> str:
+        if not value.startswith(("http://", "https://")):
+            raise ValueError(f"authorization_server must start with http:// or https://; got {value!r}")
+        return value
+
+    @field_validator("redirect_uri")
+    @classmethod
+    def _validate_redirect_uri_url(cls, value: str | None) -> str | None:
+        if value is not None and not value.startswith(("http://", "https://")):
+            raise ValueError(f"redirect_uri must start with http:// or https://; got {value!r}")
+        return value
+
+    @field_validator("resource_server_url")
+    @classmethod
+    def _validate_resource_server_url(cls, value: str | None) -> str | None:
+        if value is not None and not value.startswith(("http://", "https://")):
+            raise ValueError(f"resource_server_url must start with http:// or https://; got {value!r}")
+        return value
+
+
+CredentialConfig = Annotated[UserPatConfig | OAuthConfig, Field(discriminator="kind")]
+
+
+class TheseusSettings(BaseSettings):
+    """theseus-kit settings, loadable from env vars or a ``.env`` file.
+
+    Env nesting uses ``__``. Examples::
+
+        THESEUS_ROBOT__ROBOT_ID=robot-1
+        THESEUS_ROBOT__NAMESPACE=default
+        THESEUS_ROBOT__API_BASE_URL=https://api.example.com
+        THESEUS_CREDENTIAL__KIND=user_pat
+        THESEUS_CREDENTIAL__PAT=tfp_xxx
+        THESEUS_CREDENTIAL__ROBOT_PUBLIC_ID=myorg:12345
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="theseus_",
+        env_nested_delimiter="__",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    robot: RobotTarget
+    credential: CredentialConfig

theseus_kit/credentials.py

@@ -0,0 +1,60 @@
+"""Build a tfrs-auth ``Credential`` from theseus-kit config.
+
+``user_pat`` yields a ``tfrs_auth.PatCredential`` driven by
+``AsyncCachingTokenSource`` (token-exchange + cache + refresh).
+OAuth is handled via ``StaticTokenSource`` — see :mod:`theseus_kit.oauth`.
+theseus-kit never reimplements the exchange / refresh / retry algorithm.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from tfrs_auth import PatCredential, Scope, robot_audience, scopes_to_str
+
+from .config import CredentialConfig, OAuthConfig, UserPatConfig
+from .errors import ConfigError
+
+
+def _parse_public_id(public_id: str, *, field_name: str) -> tuple[str, str]:
+    """Parse a ``{orgSlug}:{employeeNo}`` public_id into its two components.
+
+    The format is contractually defined by Manager's ``publicid`` module and
+    mirrored in tfrs-auth's ``contract.public_id()``.
+    """
+    if ":" not in public_id:
+        raise ConfigError(f"{field_name} must be in public_id format ({{orgSlug}}:{{employeeNo}}), got {public_id!r}")
+    org_slug, employee_no = public_id.rsplit(":", 1)
+    if not org_slug or not employee_no:
+        raise ConfigError(f"{field_name} has empty org_slug or employee_no: {public_id!r}")
+    return org_slug, employee_no
+
+
+def build_credential(
+    cred: CredentialConfig,
+    *,
+    scopes: Sequence[Scope | str] = (Scope.CONFIG_READ,),
+) -> PatCredential:
+    """Construct the tfrs-auth credential for the configured source.
+
+    ``user_pat`` exchanges the user's PAT for a robot-scoped JWT via Manager's
+    token-exchange endpoint (RFC 8693).  The token ``audience`` is
+    ``robot:{public_id}`` where *public_id* identifies the target robot.
+    """
+    if isinstance(cred, UserPatConfig):
+        org_slug, employee_no = _parse_public_id(cred.robot_public_id, field_name="robot_public_id")
+        return PatCredential(
+            pat=cred.pat.get_secret_value(),
+            audience=robot_audience(org_slug, employee_no),
+            scope=scopes_to_str(scopes),
+        )
+    if isinstance(cred, OAuthConfig):
+        raise ConfigError(
+            "OAuth credentials bypass the token exchange pipeline. "
+            "The OAuth path uses a static bearer token held by the MCP Client "
+            "and injected by RobotClient — no AsyncCachingTokenSource is needed. "
+            "Use the OAuth static bearer path instead of build_credential() / build_token_source()."
+        )
+    # Closed discriminated union — fail explicitly if a new kind is added without
+    # wiring it here (decouples runtime validation from mypy type narrowing).
+    raise ConfigError(f"unsupported credential kind: {cred!r}")  # pyright: ignore[reportUnreachable]

theseus_kit/errors.py

@@ -0,0 +1,166 @@
+"""Typed errors for theseus-kit's auth + routing layer.
+
+theseus-kit surfaces tfrs-auth exchange failures and robot-side failures as
+typed exceptions so callers branch on failure mode rather than string-matching.
+All messages are scrubbed of credentials/tokens via :mod:`theseus_kit.redaction`.
+"""
+
+from __future__ import annotations
+
+from tfrs_auth.errors import (
+    InvalidClientError,
+    InvalidGrantError,
+    InvalidScopeError,
+    InvalidTargetError,
+    PaymentRequiredError,
+    RateLimitedError,
+    TemporarilyUnavailableError,
+    TfrsAuthError,
+    TransportError,
+)
+
+from .redaction import redact_secrets
+
+
+class TheseusError(Exception):
+    """Base class for all theseus-kit errors."""
+
+
+class ConfigError(TheseusError):
+    """Invalid theseus-kit configuration."""
+
+
+class RoutingConfigError(ConfigError):
+    """A routing field (namespace / rid / robot_type) is missing or malformed."""
+
+
+class CredentialError(TheseusError):
+    """The configured credential was rejected by the token endpoint."""
+
+
+class ScopeOrAudienceError(TheseusError):
+    """The requested audience / scope is not grantable for this credential."""
+
+
+class ExchangeUnavailableError(TheseusError):
+    """The token endpoint is temporarily unavailable (may be retryable)."""
+
+    def __init__(self, message: str, *, retryable: bool) -> None:
+        self.retryable = retryable
+        super().__init__(message)
+
+
+class AuthRejectedError(TheseusError):
+    """The robot rejected the request (401 / 403): credential invalid or scope insufficient."""
+
+
+class SubscriptionFrozenError(TheseusError):
+    """The target robot's organization subscription is frozen (HTTP 402)."""
+
+    def __init__(self, message: str, *, renew_url: str | None) -> None:
+        self.renew_url = renew_url
+        super().__init__(message)
+
+
+class RobotApiError(TheseusError):
+    """A non-auth robot API failure (4xx / 5xx, or network with no HTTP response)."""
+
+    def __init__(self, message: str, *, status_code: int) -> None:
+        # ``status_code == 0`` means no HTTP response was received (network failure).
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class ConfigLocatorError(TheseusError):
+    """The supplied locator string is malformed or references an unknown state."""
+
+
+class LlmsDocError(TheseusError):
+    """The requested llms.txt document path is invalid or forbidden."""
+
+
+class DraftNotFoundError(TheseusError):
+    """The requested draft setting_id does not exist (HTTP 404)."""
+
+
+class DraftConflictError(TheseusError):
+    """The draft was modified by another actor since it was read.
+
+    Carries *current_hash* so the caller can re-read and retry with the
+    latest content hash.
+    """
+
+    def __init__(self, message: str, *, current_hash: str) -> None:
+        self.current_hash = current_hash
+        super().__init__(message)
+
+
+class PublishNotConfirmedError(TheseusError):
+    """The caller must explicitly acknowledge the publish action (acknowledge_publish=True).
+
+    Publishing a draft configuration is a global, irreversible side-effect. This
+    guard forces the caller to confirm it understood the consequences before the
+    request is sent upstream.
+    """
+
+
+class PublishPreCheckError(TheseusError):
+    """A pre-publish guard failed — the root hash doesn't match, or the draft
+    structure changed since the caller last read it.
+
+    The caller should re-read the current draft state to understand the
+    discrepancy before retrying.
+    """
+
+
+class RobotValidationError(RobotApiError):
+    """The robot rejected the request body as invalid (HTTP 422).
+
+    Carries *validation_message* from TFRobotServer's ``msg`` field
+    (fell back to ``message`` if absent — the 422 handler uses ``msg``
+    instead of ``message``).
+    """
+
+    def __init__(self, message: str, *, status_code: int = 422, validation_message: str) -> None:
+        self.validation_message = validation_message
+        super().__init__(message, status_code=status_code)
+
+
+def map_exchange_error(exc: TfrsAuthError) -> TheseusError:
+    """Map a tfrs-auth exchange/network error to a theseus-kit typed error.
+
+    Called when ``AsyncCachingTokenSource.token()`` raises. Covers both the
+    OAuth error body (``TokenExchangeError`` subclasses) and the network-layer
+    ``TransportError``. Messages are scrubbed defensively.
+    """
+    message = redact_secrets(str(exc))
+    if isinstance(exc, PaymentRequiredError):
+        return SubscriptionFrozenError(
+            _hint(message, "目标机器人所属组织订阅已冻结（402），需续费后重试。"),
+            renew_url=exc.renew_url,
+        )
+    if isinstance(exc, TransportError):
+        return ExchangeUnavailableError(
+            _hint(message, "换发端点网络不可达（连接 / 超时 / DNS），可稍后重试。"),
+            retryable=True,
+        )
+    if isinstance(exc, (TemporarilyUnavailableError, RateLimitedError)):
+        return ExchangeUnavailableError(
+            _hint(message, "换发暂不可用（限流 429 / 服务不可用 503），可稍后重试。"),
+            retryable=exc.retryable,
+        )
+    if isinstance(exc, (InvalidGrantError, InvalidClientError)):
+        return CredentialError(_hint(message, "凭证被拒：检查 PAT / 机器凭证是否有效、未撤销或未过期。"))
+    if isinstance(exc, (InvalidTargetError, InvalidScopeError)):
+        return ScopeOrAudienceError(
+            _hint(
+                message,
+                "受众 / Scope 不足：确认 audience=robot:{public_id}、scope（只读=config:read）。",
+            )
+        )
+    return TheseusError(_hint(message, "令牌换发失败。"))
+
+
+def _hint(message: str, hint: str) -> str:
+    body = message.strip()
+    return f"{hint}（上游：{body}）" if body else hint