dockerhub-api 0.1.0__py3-none-any.whl

dockerhub_api/dockerhub_response_models.py

@@ -0,0 +1,344 @@
+"""Pydantic response models for the Docker Hub API client.
+
+CONCEPT:HUB-1.0 — core wrapper.
+
+Models are intentionally lenient (``extra="allow"``, optional fields) so they
+survive Docker Hub schema evolution: known fields get typed, unknown fields
+ride along. Client methods validate response data against these models when
+the shape is known and fall back to raw JSON when validation fails.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class HubModel(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+
+class RateLimit(HubModel):
+    """Snapshot of the ``X-RateLimit-*`` headers from the latest response."""
+
+    limit: int | None = Field(default=None, description="Request ceiling")
+    remaining: int | None = Field(default=None, description="Requests remaining")
+    reset: int | None = Field(default=None, description="Window reset (epoch s)")
+
+
+class Page(HubModel):
+    """Standard Docker Hub page envelope (``count``/``next``/``previous``)."""
+
+    count: int | None = None
+    next: str | None = None
+    previous: str | None = None
+    results: list[Any] | None = None
+
+
+class JwtToken(HubModel):
+    """``POST /v2/auth/token`` response."""
+
+    access_token: str | None = None
+    token: str | None = None
+
+
+class LoginResult(HubModel):
+    """``POST /v2/users/login`` / ``POST /v2/users/2fa-login`` response."""
+
+    token: str | None = None
+    refresh_token: str | None = None
+    detail: str | None = None
+    login_2fa_token: str | None = None
+
+
+class AccessToken(HubModel):
+    """A personal access token record."""
+
+    uuid: str | None = None
+    token_label: str | None = None
+    token: str | None = Field(
+        default=None, description="Plaintext token — only present on creation"
+    )
+    scopes: list[str] | None = None
+    is_active: bool | None = None
+    client_id: str | None = None
+    creator_ip: str | None = None
+    creator_ua: str | None = None
+    created_at: str | None = None
+    last_used: str | None = None
+    generated_by: str | None = None
+
+
+class AccessTokenPage(Page):
+    active_count: int | None = None
+    results: list[AccessToken] | None = None  # type: ignore[assignment]
+
+
+class OrgAccessToken(HubModel):
+    """An organization access token record."""
+
+    id: str | None = None
+    uuid: str | None = None
+    label: str | None = None
+    description: str | None = None
+    token: str | None = Field(
+        default=None, description="Plaintext token — only present on creation"
+    )
+    scopes: list[str] | None = None
+    resources: list[dict] | None = None
+    is_active: bool | None = None
+    created_at: str | None = None
+    expires_at: str | None = None
+
+
+class OrgAccessTokenPage(Page):
+    results: list[OrgAccessToken] | None = None  # type: ignore[assignment]
+
+
+class AuditLogEvent(HubModel):
+    """One audit-log entry."""
+
+    account: str | None = None
+    action: str | None = None
+    name: str | None = None
+    actor: str | None = None
+    actor_ip: str | None = None
+    data: dict | None = None
+    timestamp: str | None = None
+
+
+class AuditLogPage(HubModel):
+    logs: list[AuditLogEvent] | None = None
+    count: int | None = None
+
+
+class AuditLogActions(HubModel):
+    """``GET /v2/auditlogs/{account}/actions`` response."""
+
+    actions: dict | list | None = None
+
+
+class RestrictedImages(HubModel):
+    enabled: bool | None = None
+    allow_official_images: bool | None = None
+    allow_verified_publishers: bool | None = None
+
+
+class OrgSettings(HubModel):
+    """``GET|PUT /v2/orgs/{name}/settings`` response."""
+
+    restricted_images: RestrictedImages | None = None
+
+
+class Repository(HubModel):
+    """A Docker Hub image repository."""
+
+    name: str | None = None
+    namespace: str | None = None
+    repository_type: str | None = None
+    description: str | None = None
+    full_description: str | None = None
+    registry: str | None = None
+    is_private: bool | None = None
+    status: int | str | None = None
+    star_count: int | None = None
+    pull_count: int | None = None
+    last_updated: str | None = None
+    date_registered: str | None = None
+    affiliation: str | None = None
+    media_types: list[str] | None = None
+
+
+class RepositoryPage(Page):
+    results: list[Repository] | None = None  # type: ignore[assignment]
+
+
+class TagImage(HubModel):
+    architecture: str | None = None
+    os: str | None = None
+    digest: str | None = None
+    size: int | None = None
+    status: str | None = None
+    last_pushed: str | None = None
+    last_pulled: str | None = None
+
+
+class Tag(HubModel):
+    """A repository tag."""
+
+    id: int | None = None
+    name: str | None = None
+    repository: int | str | None = None
+    full_size: int | None = None
+    digest: str | None = None
+    images: list[TagImage] | None = None
+    last_updated: str | None = None
+    last_updater_username: str | None = None
+    tag_status: str | None = None
+    tag_last_pulled: str | None = None
+    tag_last_pushed: str | None = None
+    v2: bool | str | None = None
+    content_type: str | None = None
+    media_type: str | None = None
+
+
+class TagPage(Page):
+    results: list[Tag] | None = None  # type: ignore[assignment]
+
+
+class ImmutableTagsSettings(HubModel):
+    """``PATCH .../immutabletags`` response."""
+
+    enabled: bool | None = None
+    rules: list[str] | None = None
+
+
+class ImmutableTagsVerification(HubModel):
+    """``POST .../immutabletags/verify`` response."""
+
+    enabled: bool | None = None
+    rules: list[str] | None = None
+    results: list[dict] | None = None
+    errors: list[dict] | None = None
+
+
+class RepositoryGroup(HubModel):
+    """``POST /v2/repositories/{ns}/{repo}/groups`` response."""
+
+    group_id: int | str | None = None
+    group_name: str | None = None
+    permission: str | None = None
+
+
+class OrgMember(HubModel):
+    """An organization member."""
+
+    id: str | None = None
+    username: str | None = None
+    full_name: str | None = None
+    email: str | None = None
+    role: str | None = None
+    type: str | None = None
+    groups: list[str] | None = None
+    is_guest: bool | None = None
+    last_logged_in_date: str | None = None
+    joined_at: str | None = None
+
+
+class OrgMemberPage(Page):
+    results: list[OrgMember] | None = None  # type: ignore[assignment]
+
+
+class Invite(HubModel):
+    """An organization invite."""
+
+    id: str | None = None
+    invitee: str | None = None
+    inviter: str | None = None
+    org: str | None = None
+    team: str | None = None
+    role: str | None = None
+    created_at: str | None = None
+    status: str | None = None
+
+
+class InvitePage(Page):
+    data: list[Invite] | None = None
+    results: list[Invite] | None = None  # type: ignore[assignment]
+
+
+class BulkInviteResult(HubModel):
+    """``POST /v2/invites/bulk`` response."""
+
+    org: str | None = None
+    team: str | None = None
+    role: str | None = None
+    dry_run: bool | None = None
+    invitees: list[dict] | list[str] | None = None
+    valid: list[Any] | None = None
+    invalid: list[Any] | None = None
+
+
+class Group(HubModel):
+    """An organization group (team)."""
+
+    id: int | str | None = None
+    name: str | None = None
+    description: str | None = None
+    member_count: int | None = None
+
+
+class GroupPage(Page):
+    results: list[Group] | None = None  # type: ignore[assignment]
+
+
+class ScimName(HubModel):
+    givenName: str | None = None
+    familyName: str | None = None
+
+
+class ScimEmail(HubModel):
+    value: str | None = None
+    primary: bool | None = None
+
+
+class ScimUser(HubModel):
+    """A SCIM 2.0 User resource."""
+
+    schemas: list[str] | None = None
+    id: str | None = None
+    userName: str | None = None
+    name: ScimName | None = None
+    emails: list[ScimEmail] | None = None
+    active: bool | None = None
+    groups: list[dict] | None = None
+    meta: dict | None = None
+
+
+class ScimListResponse(HubModel):
+    """SCIM 2.0 list envelope (``ListResponse``)."""
+
+    schemas: list[str] | None = None
+    totalResults: int | None = None
+    startIndex: int | None = None
+    itemsPerPage: int | None = None
+    Resources: list[dict] | None = None
+
+
+class ScimServiceProviderConfig(HubModel):
+    schemas: list[str] | None = None
+    patch: dict | None = None
+    bulk: dict | None = None
+    filter: dict | None = None
+    changePassword: dict | None = None
+    sort: dict | None = None
+    etag: dict | None = None
+    authenticationSchemes: list[dict] | None = None
+
+
+class ScimResourceType(HubModel):
+    schemas: list[str] | None = None
+    id: str | None = None
+    name: str | None = None
+    endpoint: str | None = None
+    schema_uri: str | None = Field(default=None, alias="schema")
+
+
+class ScimSchema(HubModel):
+    id: str | None = None
+    name: str | None = None
+    description: str | None = None
+    attributes: list[dict] | None = None
+
+
+def validate_lenient(model: type[BaseModel], data: Any) -> Any:
+    """Validate ``data`` against ``model``; fall back to the raw data.
+
+    Keeps client results JSON-serializable while still exercising the typed
+    models whenever the payload matches the documented shape.
+    """
+    if data is None:
+        return None
+    try:
+        return model.model_validate(data).model_dump(mode="json", exclude_none=True)
+    except Exception:  # pragma: no cover - lenient by design
+        return data

dockerhub_api/main_agent.json

@@ -0,0 +1,14 @@
+{
+  "task": "main-agent",
+  "input": "# main-agent\n\nYou are the Docker Hub operations agent for this workspace. Your goal is to help the user manage Docker Hub repositories, tags, access tokens, organizations, teams, audit logs, and SCIM provisioning.\n\n### Core Principles\n* Be concise and efficient.\n* Prefer read-only inspection before any write.\n* Destructive operations (deletes, org-settings writes) are gated behind DOCKERHUB_ALLOW_DESTRUCTIVE — confirm intent before enabling.\n* Verify your work before concluding.\n\nYour personality:\n* **Emoji:** 🐳\n* **Vibe:** Professional, efficient, helpful",
+  "type": "prompt",
+  "description": "The Docker Hub operations agent for this workspace.",
+  "tools": [
+    "workspace-manager",
+    "agent-workflows"
+  ],
+  "topic": "Docker Hub Administration",
+  "tone": "technical and precise",
+  "style": "professional assistant",
+  "goal": "Manage Docker Hub repositories, tokens, organizations, teams, and provisioning."
+}

dockerhub_api/mcp/__init__.py

@@ -0,0 +1,120 @@
+"""MCP tool registration modules for dockerhub-api.
+
+CONCEPT:HUB-1.4 — action-routed MCP surface. Each module registers one
+consolidated, action-routed tool; this package provides the shared client
+resolution, parameter parsing, secret redaction, and error-envelope helpers.
+"""
+
+import json
+from typing import Any
+
+from agent_utilities.core.exceptions import (
+    ApiError,
+    AuthError,
+    MissingParameterError,
+    ParameterError,
+    UnauthorizedError,
+)
+
+from dockerhub_api.api.api_client_base import DestructiveOperationError
+
+#: Keys whose values are always masked in MCP tool results.
+SECRET_KEYS = {"secret", "password", "access_token", "refresh_token", "jwt"}
+REDACTED = "***redacted***"
+
+
+def get_hub_client():
+    """Resolve the Docker Hub client late so tests/deployments can rebind
+    ``dockerhub_api.auth.get_client``."""
+    from dockerhub_api.auth import get_client
+
+    return get_client()
+
+
+def parse_params(params_json: str) -> dict[str, Any]:
+    """Parse the ``params_json`` tool argument, dropping ``None`` values."""
+    kwargs = json.loads(params_json) if params_json else {}
+    if not isinstance(kwargs, dict):
+        raise ValueError("params_json must decode to a JSON object")
+    return {k: v for k, v in kwargs.items() if v is not None}
+
+
+def redact_secrets(data: Any, allow_keys: set[str] | None = None) -> Any:
+    """Recursively mask secret-bearing fields in a tool result.
+
+    ``allow_keys`` whitelists keys that must stay visible for this one call
+    (e.g. the plaintext ``token`` returned exactly once on PAT creation).
+    """
+    allow = allow_keys or set()
+    if isinstance(data, dict):
+        return {
+            key: (
+                REDACTED
+                if key in SECRET_KEYS and key not in allow and value
+                else redact_secrets(value, allow)
+            )
+            for key, value in data.items()
+        }
+    if isinstance(data, list):
+        return [redact_secrets(item, allow) for item in data]
+    return data
+
+
+def error_envelope(error: Exception) -> dict[str, Any]:
+    """Map a client exception to the MCP error envelope."""
+    return {"error": {"type": type(error).__name__, "message": str(error)}}
+
+
+HANDLED_ERRORS = (
+    ApiError,
+    AuthError,
+    UnauthorizedError,
+    ParameterError,
+    MissingParameterError,
+    DestructiveOperationError,
+    ValueError,
+)
+
+
+def run_action(handlers: dict, action: str, kwargs: dict[str, Any]) -> Any:
+    """Dispatch ``action`` to its handler, mapping errors to the envelope."""
+    handler = handlers.get(action)
+    if handler is None:
+        return {
+            "error": {
+                "type": "UnknownAction",
+                "message": f"Unknown action: {action!r}. "
+                f"Valid actions: {sorted(handlers)}",
+            }
+        }
+    try:
+        return handler(**kwargs)
+    except HANDLED_ERRORS as error:
+        return error_envelope(error)
+
+
+from dockerhub_api.mcp.mcp_admin import register_admin_tools
+from dockerhub_api.mcp.mcp_audit import register_audit_tools
+from dockerhub_api.mcp.mcp_auth import register_auth_tools
+from dockerhub_api.mcp.mcp_org import register_org_tools
+from dockerhub_api.mcp.mcp_repos import register_repos_tools
+from dockerhub_api.mcp.mcp_scim import register_scim_tools
+from dockerhub_api.mcp.mcp_teams import register_teams_tools
+
+__all__ = [
+    "HANDLED_ERRORS",
+    "REDACTED",
+    "SECRET_KEYS",
+    "error_envelope",
+    "get_hub_client",
+    "parse_params",
+    "redact_secrets",
+    "register_admin_tools",
+    "register_audit_tools",
+    "register_auth_tools",
+    "register_org_tools",
+    "register_repos_tools",
+    "register_scim_tools",
+    "register_teams_tools",
+    "run_action",
+]

dockerhub_api/mcp/mcp_admin.py

@@ -0,0 +1,45 @@
+"""MCP tool for Docker Hub client telemetry and identity introspection.
+
+CONCEPT:HUB-1.4 — action-routed MCP surface.
+CONCEPT:HUB-1.2 — rate-limit telemetry.
+"""
+
+from typing import Any
+
+from fastmcp import Context, FastMCP
+from fastmcp.dependencies import Depends
+from pydantic import Field
+
+from dockerhub_api.mcp import get_hub_client, parse_params, redact_secrets, run_action
+
+
+def register_admin_tools(mcp: FastMCP):
+    @mcp.tool(tags={"admin"})
+    async def hub_admin(
+        action: str = Field(
+            description="Action to perform. Must be one of: 'rate_limit', 'whoami'"
+        ),
+        params_json: str = Field(
+            default="{}", description="JSON string of parameters to pass to the action."
+        ),
+        client=Depends(get_hub_client),
+        ctx: Context | None = Field(
+            default=None, description="MCP context for progress reporting"
+        ),
+    ) -> Any:
+        """Client diagnostics: 'rate_limit' returns the latest
+        X-RateLimit-* snapshot observed by the client; 'whoami' introspects
+        the active credential locally (decoded JWT claims, no network call).
+        """
+        if ctx:
+            await ctx.info("Executing tool...")
+        try:
+            kwargs = parse_params(params_json)
+        except Exception as e:
+            return {"error": f"Invalid params_json: {e}"}
+
+        handlers = {
+            "rate_limit": client.get_rate_limit,
+            "whoami": client.whoami,
+        }
+        return redact_secrets(run_action(handlers, action, kwargs))

dockerhub_api/mcp/mcp_audit.py

@@ -0,0 +1,44 @@
+"""MCP tool for Docker Hub audit logs.
+
+CONCEPT:HUB-1.4 — action-routed MCP surface.
+"""
+
+from typing import Any
+
+from fastmcp import Context, FastMCP
+from fastmcp.dependencies import Depends
+from pydantic import Field
+
+from dockerhub_api.mcp import get_hub_client, parse_params, redact_secrets, run_action
+
+
+def register_audit_tools(mcp: FastMCP):
+    @mcp.tool(tags={"audit"})
+    async def hub_audit(
+        action: str = Field(
+            description="Action to perform. Must be one of: 'logs', 'actions'"
+        ),
+        params_json: str = Field(
+            default="{}", description="JSON string of parameters to pass to the action."
+        ),
+        client=Depends(get_hub_client),
+        ctx: Context | None = Field(
+            default=None, description="MCP context for progress reporting"
+        ),
+    ) -> Any:
+        """Read a Docker Hub account's audit trail: 'logs' lists events
+        (filters: action, name, actor, from_date, to_date, page, page_size),
+        'actions' lists the available action names.
+        """
+        if ctx:
+            await ctx.info("Executing tool...")
+        try:
+            kwargs = parse_params(params_json)
+        except Exception as e:
+            return {"error": f"Invalid params_json: {e}"}
+
+        handlers = {
+            "logs": client.get_audit_logs,
+            "actions": client.get_audit_log_actions,
+        }
+        return redact_secrets(run_action(handlers, action, kwargs))

dockerhub_api/mcp/mcp_auth.py

@@ -0,0 +1,66 @@
+"""MCP tool for Docker Hub auth and token lifecycle.
+
+CONCEPT:HUB-1.4 — action-routed MCP surface.
+"""
+
+from typing import Any
+
+from fastmcp import Context, FastMCP
+from fastmcp.dependencies import Depends
+from pydantic import Field
+
+from dockerhub_api.mcp import get_hub_client, parse_params, redact_secrets, run_action
+
+
+def register_auth_tools(mcp: FastMCP):
+    @mcp.tool(tags={"auth"})
+    async def hub_auth(
+        action: str = Field(
+            description=(
+                "Action to perform. Must be one of: 'create_token', 'login' "
+                "(deprecated), 'two_factor_login', 'list_pats', 'create_pat', "
+                "'get_pat', 'update_pat', 'delete_pat', 'list_oats', "
+                "'create_oat', 'get_oat', 'update_oat', 'delete_oat'"
+            )
+        ),
+        params_json: str = Field(
+            default="{}", description="JSON string of parameters to pass to the action."
+        ),
+        client=Depends(get_hub_client),
+        ctx: Context | None = Field(
+            default=None, description="MCP context for progress reporting"
+        ),
+    ) -> Any:
+        """Manage Docker Hub authentication, personal access tokens (PATs),
+        and organization access tokens (OATs).
+
+        Bearer JWTs are minted/cached client-side and redacted from results.
+        Plaintext PAT/OAT values appear exactly once, on creation. Token
+        deletion requires DOCKERHUB_ALLOW_DESTRUCTIVE=True.
+        """
+        if ctx:
+            await ctx.info("Executing tool...")
+        try:
+            kwargs = parse_params(params_json)
+        except Exception as e:
+            return {"error": f"Invalid params_json: {e}"}
+
+        handlers = {
+            "create_token": client.create_auth_token,
+            "login": client.login,
+            "two_factor_login": client.two_factor_login,
+            "list_pats": client.get_access_tokens,
+            "create_pat": client.create_access_token,
+            "get_pat": client.get_access_token,
+            "update_pat": client.update_access_token,
+            "delete_pat": client.delete_access_token,
+            "list_oats": client.get_org_access_tokens,
+            "create_oat": client.create_org_access_token,
+            "get_oat": client.get_org_access_token,
+            "update_oat": client.update_org_access_token,
+            "delete_oat": client.delete_org_access_token,
+        }
+        result = run_action(handlers, action, kwargs)
+        # Plaintext tokens are shown exactly once — on creation.
+        allow_keys = {"token"} if action in ("create_pat", "create_oat") else set()
+        return redact_secrets(result, allow_keys=allow_keys)

dockerhub_api/mcp/mcp_org.py

@@ -0,0 +1,58 @@
+"""MCP tool for Docker Hub organization members, settings, and invites.
+
+CONCEPT:HUB-1.4 — action-routed MCP surface.
+"""
+
+from typing import Any
+
+from fastmcp import Context, FastMCP
+from fastmcp.dependencies import Depends
+from pydantic import Field
+
+from dockerhub_api.mcp import get_hub_client, parse_params, redact_secrets, run_action
+
+
+def register_org_tools(mcp: FastMCP):
+    @mcp.tool(tags={"org"})
+    async def hub_org(
+        action: str = Field(
+            description=(
+                "Action to perform. Must be one of: 'get_settings', "
+                "'update_settings', 'list_members', 'export_members', "
+                "'update_member', 'remove_member', 'list_invites', "
+                "'delete_invite', 'resend_invite', 'bulk_invite'"
+            )
+        ),
+        params_json: str = Field(
+            default="{}", description="JSON string of parameters to pass to the action."
+        ),
+        client=Depends(get_hub_client),
+        ctx: Context | None = Field(
+            default=None, description="MCP context for progress reporting"
+        ),
+    ) -> Any:
+        """Manage a Docker Hub organization: settings (restricted images),
+        member roster and roles, CSV export, and invites (single, resend,
+        bulk with dry_run). Member removal, invite deletion, and settings
+        writes require DOCKERHUB_ALLOW_DESTRUCTIVE=True.
+        """
+        if ctx:
+            await ctx.info("Executing tool...")
+        try:
+            kwargs = parse_params(params_json)
+        except Exception as e:
+            return {"error": f"Invalid params_json: {e}"}
+
+        handlers = {
+            "get_settings": client.get_org_settings,
+            "update_settings": client.update_org_settings,
+            "list_members": client.get_org_members,
+            "export_members": client.export_org_members,
+            "update_member": client.update_org_member,
+            "remove_member": client.remove_org_member,
+            "list_invites": client.get_org_invites,
+            "delete_invite": client.delete_invite,
+            "resend_invite": client.resend_invite,
+            "bulk_invite": client.bulk_invite,
+        }
+        return redact_secrets(run_action(handlers, action, kwargs))