agentskills-http 0.2.0__tar.gz → 0.2.1__tar.gz

{agentskills_http-0.2.0 → agentskills_http-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentskills-http
-Version: 0.2.0
+Version: 0.2.1
 Summary: HTTP-based skill providers for the Agent Skills format (https://agentskills.io)
 License: MIT
 Author: Pratik Panda
@@ -13,9 +13,9 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
-Requires-Dist: agentskills-core (>=0.1.0)
-Requires-Dist: httpx (>=0.27)
-Requires-Dist: pyyaml (>=6.0)
+Requires-Dist: agentskills-core (>=0.1.0,<1.0)
+Requires-Dist: httpx (>=0.27,<1.0)
+Requires-Dist: pyyaml (>=6.0,<7.0)
 Project-URL: Homepage, https://agentskills.io
 Project-URL: Repository, https://github.com/pratikxpanda/agentskills-sdk
 Description-Content-Type: text/markdown
@@ -93,7 +93,18 @@ provider = HTTPStaticFileSkillProvider("https://cdn.example.com/skills", client=
 
 ## API
 
-### `HTTPStaticFileSkillProvider(base_url, *, client=None, headers=None)`
+### `HTTPStaticFileSkillProvider(base_url, *, client=None, headers=None, params=None, require_tls=False, max_response_bytes=10_485_760)`
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `base_url` | `str` | — | Root URL where the skill tree is hosted |
+| `client` | `AsyncClient \| None` | `None` | Pre-configured httpx client (caller manages lifecycle) |
+| `headers` | `dict \| None` | `None` | Extra headers sent with every request |
+| `params` | `dict \| None` | `None` | Query parameters appended to every request |
+| `require_tls` | `bool` | `False` | Reject `http://` URLs with `ValueError` |
+| `max_response_bytes` | `int` | `10_485_760` | Maximum allowed response size in bytes |
+
+> **Note:** `client` and `headers`/`params` are mutually exclusive. Configure headers and params on the client directly when providing your own.
 
 | Method | Returns | Description |
 | --- | --- | --- |
@@ -117,6 +128,26 @@ Supports `async with` for automatic cleanup.
 
 All exceptions inherit from `AgentSkillsError`.
 
+## Security
+
+- **Input validation** — Skill IDs and resource names are validated against a safe-character pattern (`^[a-zA-Z0-9][a-zA-Z0-9._-]*$`) to prevent path-traversal and injection attacks.
+- **TLS warnings** — A `UserWarning` is emitted when `base_url` uses unencrypted HTTP. Set `require_tls=True` to reject HTTP URLs entirely.
+- **Redirect protection** — The internally-created HTTP client does not follow redirects by default, preventing open-redirect SSRF.
+- **Timeouts** — Default 30-second timeout on all HTTP requests.
+- **Response size limits** — Responses exceeding 10 MB (default) are rejected before processing. Configure via `max_response_bytes`.
+- **Error-message sanitization** — Error messages omit URLs and include only status codes and generic descriptions, preventing internal URL leakage.
+
+For the full security policy, see [SECURITY.md](../../../SECURITY.md).
+
+## Deployment Considerations
+
+- **Rate limiting** — The SDK does not enforce rate limits on MCP tool
+  calls or HTTP requests. Deploy behind a reverse proxy or API gateway
+  that provides rate limiting in production environments.
+- **Credential management** — Do not store secrets (API keys, SAS
+  tokens, Authorization headers) in config files committed to version
+  control. Use environment variables or a secret manager instead.
+
 ## License
 
 MIT

{agentskills_http-0.2.0 → agentskills_http-0.2.1}/README.md

@@ -71,7 +71,18 @@ provider = HTTPStaticFileSkillProvider("https://cdn.example.com/skills", client=
 
 ## API
 
-### `HTTPStaticFileSkillProvider(base_url, *, client=None, headers=None)`
+### `HTTPStaticFileSkillProvider(base_url, *, client=None, headers=None, params=None, require_tls=False, max_response_bytes=10_485_760)`
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `base_url` | `str` | — | Root URL where the skill tree is hosted |
+| `client` | `AsyncClient \| None` | `None` | Pre-configured httpx client (caller manages lifecycle) |
+| `headers` | `dict \| None` | `None` | Extra headers sent with every request |
+| `params` | `dict \| None` | `None` | Query parameters appended to every request |
+| `require_tls` | `bool` | `False` | Reject `http://` URLs with `ValueError` |
+| `max_response_bytes` | `int` | `10_485_760` | Maximum allowed response size in bytes |
+
+> **Note:** `client` and `headers`/`params` are mutually exclusive. Configure headers and params on the client directly when providing your own.
 
 | Method | Returns | Description |
 | --- | --- | --- |
@@ -95,6 +106,26 @@ Supports `async with` for automatic cleanup.
 
 All exceptions inherit from `AgentSkillsError`.
 
+## Security
+
+- **Input validation** — Skill IDs and resource names are validated against a safe-character pattern (`^[a-zA-Z0-9][a-zA-Z0-9._-]*$`) to prevent path-traversal and injection attacks.
+- **TLS warnings** — A `UserWarning` is emitted when `base_url` uses unencrypted HTTP. Set `require_tls=True` to reject HTTP URLs entirely.
+- **Redirect protection** — The internally-created HTTP client does not follow redirects by default, preventing open-redirect SSRF.
+- **Timeouts** — Default 30-second timeout on all HTTP requests.
+- **Response size limits** — Responses exceeding 10 MB (default) are rejected before processing. Configure via `max_response_bytes`.
+- **Error-message sanitization** — Error messages omit URLs and include only status codes and generic descriptions, preventing internal URL leakage.
+
+For the full security policy, see [SECURITY.md](../../../SECURITY.md).
+
+## Deployment Considerations
+
+- **Rate limiting** — The SDK does not enforce rate limits on MCP tool
+  calls or HTTP requests. Deploy behind a reverse proxy or API gateway
+  that provides rate limiting in production environments.
+- **Credential management** — Do not store secrets (API keys, SAS
+  tokens, Authorization headers) in config files committed to version
+  control. Use environment variables or a secret manager instead.
+
 ## License
 
 MIT

{agentskills_http-0.2.0 → agentskills_http-0.2.1}/agentskills_http/static.py

@@ -28,8 +28,11 @@ for non-blocking HTTP requests.
 
 from __future__ import annotations
 
+import logging
+import re
+import warnings
 from typing import Any
-from urllib.parse import quote
+from urllib.parse import quote, urlparse
 
 import httpx
 
@@ -41,6 +44,20 @@ from agentskills_core import (
     split_frontmatter,
 )
 
+_logger = logging.getLogger(__name__)
+
+# Input validation: identifiers (skill_id, resource name) must be safe
+# URL path segments.  Allows alphanumeric, hyphens, dots, underscores.
+# Must start with an alphanumeric character.  No path separators or
+# traversal sequences (e.g. ``../``).
+_SAFE_IDENTIFIER_RE = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._-]*$")
+
+#: Default maximum HTTP response size in bytes (10 MB).
+DEFAULT_MAX_RESPONSE_BYTES: int = 10 * 1024 * 1024
+
+#: Default HTTP request timeout in seconds.
+DEFAULT_TIMEOUT_SECONDS: float = 30.0
+
 
 class HTTPStaticFileSkillProvider(SkillProvider):
     """Skill provider backed by a static HTTP file host.
@@ -60,10 +77,20 @@ class HTTPStaticFileSkillProvider(SkillProvider):
             slash is stripped automatically.
         client: Optional pre-configured :class:`httpx.AsyncClient`.
             When provided, the caller is responsible for closing it.
+            The provider will still enforce *max_response_bytes* but
+            will **not** override the client's timeout or redirect
+            settings.
         headers: Optional extra headers sent with every request (e.g.
             ``Authorization``).
         params: Optional query parameters appended to every request
             (e.g. SAS tokens for Azure Blob Storage).
+        require_tls: If ``True``, reject ``http://`` base URLs with
+            a :class:`ValueError`.  Defaults to ``False``, which
+            allows HTTP but emits a :class:`UserWarning`.
+        max_response_bytes: Maximum allowed response size in bytes.
+            Responses exceeding this limit raise
+            :class:`~agentskills_core.AgentSkillsError`.  Defaults to
+            10 MB.
 
     Example::
 
@@ -83,15 +110,40 @@ class HTTPStaticFileSkillProvider(SkillProvider):
         client: httpx.AsyncClient | None = None,
         headers: dict[str, str] | None = None,
         params: dict[str, str] | None = None,
+        require_tls: bool = False,
+        max_response_bytes: int = DEFAULT_MAX_RESPONSE_BYTES,
     ) -> None:
         if client is not None and (headers is not None or params is not None):
             raise ValueError(
                 "Cannot specify both 'client' and 'headers'/'params'. "
                 "Configure headers and params on the client directly."
             )
+
+        # TLS enforcement
+        parsed = urlparse(base_url)
+        if parsed.scheme == "http":
+            if require_tls:
+                raise ValueError(
+                    "require_tls is enabled but base_url uses plain HTTP. "
+                    "Use an HTTPS URL or set require_tls=False."
+                )
+            warnings.warn(
+                "base_url uses unencrypted HTTP. "
+                "Skill content fetched over HTTP is vulnerable to "
+                "man-in-the-middle attacks. Use HTTPS in production.",
+                UserWarning,
+                stacklevel=2,
+            )
+
         self._base_url = base_url.rstrip("/")
+        self._max_response_bytes = max_response_bytes
         self._owns_client = client is None
-        self._client = client or httpx.AsyncClient(headers=headers, params=params)
+        self._client = client or httpx.AsyncClient(
+            headers=headers,
+            params=params,
+            timeout=httpx.Timeout(DEFAULT_TIMEOUT_SECONDS),
+            follow_redirects=False,
+        )
 
     async def aclose(self) -> None:
         """Close the underlying HTTP client if it is owned by this provider."""
@@ -104,6 +156,24 @@ class HTTPStaticFileSkillProvider(SkillProvider):
     async def __aexit__(self, *exc: object) -> None:
         await self.aclose()
 
+    # ------------------------------------------------------------------
+    # Input validation
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _validate_identifier(value: str, label: str) -> None:
+        """Raise :class:`ValueError` if *value* is not a safe URL path segment.
+
+        Prevents path-traversal attacks (e.g. ``../``) and other
+        injection via ``skill_id`` or resource ``name``.
+        """
+        if not _SAFE_IDENTIFIER_RE.match(value):
+            raise ValueError(
+                f"Invalid {label}: {value!r} — must start with an "
+                f"alphanumeric character and contain only alphanumeric "
+                f"characters, hyphens, dots, and underscores"
+            )
+
     # ------------------------------------------------------------------
     # Metadata & body
     # ------------------------------------------------------------------
@@ -208,18 +278,23 @@ class HTTPStaticFileSkillProvider(SkillProvider):
 
         Raises:
             SkillNotFoundError: On 404.
-            AgentSkillsError: On other HTTP or connection errors.
+            AgentSkillsError: On other HTTP or connection errors,
+                or if the response exceeds *max_response_bytes*.
         """
         try:
             resp = await self._client.get(url)
         except httpx.HTTPError as exc:
-            raise AgentSkillsError(f"HTTP request failed: {url}") from exc
+            raise AgentSkillsError("HTTP request failed") from exc
         if resp.status_code == 404:
-            raise SkillNotFoundError(f"Not found: {url}")
+            raise SkillNotFoundError("Skill content not found")
         try:
             resp.raise_for_status()
         except httpx.HTTPStatusError as exc:
-            raise AgentSkillsError(f"HTTP {resp.status_code} error for {url}") from exc
+            raise AgentSkillsError(f"HTTP {resp.status_code} error") from exc
+        if len(resp.content) > self._max_response_bytes:
+            raise AgentSkillsError(
+                f"Response exceeds maximum size ({self._max_response_bytes} bytes)"
+            )
         return resp.text
 
     async def _get_bytes(self, url: str) -> bytes:
@@ -227,26 +302,34 @@ class HTTPStaticFileSkillProvider(SkillProvider):
 
         Raises:
             ResourceNotFoundError: On 404.
-            AgentSkillsError: On other HTTP or connection errors.
+            AgentSkillsError: On other HTTP or connection errors,
+                or if the response exceeds *max_response_bytes*.
         """
         try:
             resp = await self._client.get(url)
         except httpx.HTTPError as exc:
-            raise AgentSkillsError(f"HTTP request failed: {url}") from exc
+            raise AgentSkillsError("HTTP request failed") from exc
         if resp.status_code == 404:
-            raise ResourceNotFoundError(f"Not found: {url}")
+            raise ResourceNotFoundError("Resource not found")
         try:
             resp.raise_for_status()
         except httpx.HTTPStatusError as exc:
-            raise AgentSkillsError(f"HTTP {resp.status_code} error for {url}") from exc
+            raise AgentSkillsError(f"HTTP {resp.status_code} error") from exc
+        if len(resp.content) > self._max_response_bytes:
+            raise AgentSkillsError(
+                f"Response exceeds maximum size ({self._max_response_bytes} bytes)"
+            )
         return resp.content
 
     async def _get_skill_md(self, skill_id: str) -> str:
         """Fetch the full text of a skill's ``SKILL.md``."""
-        url = f"{self._base_url}/{quote(skill_id)}/SKILL.md"
+        self._validate_identifier(skill_id, "skill_id")
+        url = f"{self._base_url}/{quote(skill_id, safe='')}/SKILL.md"
         return await self._get_text(url)
 
     async def _get_resource(self, skill_id: str, subdir: str, name: str) -> bytes:
         """Fetch a single resource file from a skill subdirectory."""
-        url = f"{self._base_url}/{quote(skill_id)}/{subdir}/{quote(name)}"
+        self._validate_identifier(skill_id, "skill_id")
+        self._validate_identifier(name, "resource name")
+        url = f"{self._base_url}/{quote(skill_id, safe='')}/{subdir}/{quote(name, safe='')}"
         return await self._get_bytes(url)

{agentskills_http-0.2.0 → agentskills_http-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "agentskills-http"
-version = "0.2.0"
+version = "0.2.1"
 description = "HTTP-based skill providers for the Agent Skills format (https://agentskills.io)"
 license = "MIT"
 authors = ["Pratik Panda"]
@@ -18,9 +18,9 @@ classifiers = [
 
 [tool.poetry.dependencies]
 python = ">=3.12,<4.0"
-agentskills-core = ">=0.1.0"
-httpx = ">=0.27"
-pyyaml = ">=6.0"
+agentskills-core = ">=0.1.0,<1.0"
+httpx = ">=0.27,<1.0"
+pyyaml = ">=6.0,<7.0"
 
 [build-system]
 requires = ["poetry-core"]