instabox 0.1.0__py3-none-any.whl

instabox/__init__.py

@@ -0,0 +1,84 @@
+"""Python SDK for the InstaBox API (https://instabox.sh).
+
+InstaBox gives every agent a Linux machine of its own in the cloud.
+This SDK wraps the REST API: create, start, stop, pause and resume machines,
+run commands, read and write files, take snapshots, publish ports and track
+async operations.
+
+Quick start::
+
+    from instabox import Client
+
+    client = Client(api_key="ibk_...")
+    op = client.machines.create(name="dev")
+    op = client.operations.wait(op.id)
+    result = client.machines.exec("dev", cmd="echo hello")
+"""
+
+from __future__ import annotations
+
+from ._policy import ToolPolicy
+from .async_client import AsyncClient
+from .async_machine import AsyncMachineHandle
+from .client import Client
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InstaboxError,
+    NotFoundError,
+    PaymentRequiredError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    TimeoutExceededError,
+)
+from .machine import MachineHandle
+from .models import (
+    CurrentUser,
+    ExecResult,
+    FileEntry,
+    FileListing,
+    Machine,
+    Operation,
+    Port,
+    Snapshot,
+    Spec,
+    Template,
+    UploadUrl,
+    Usage,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "APIError",
+    "AsyncClient",
+    "AsyncMachineHandle",
+    "AuthenticationError",
+    "BadRequestError",
+    "Client",
+    "ConflictError",
+    "CurrentUser",
+    "ExecResult",
+    "FileEntry",
+    "FileListing",
+    "InstaboxError",
+    "Machine",
+    "MachineHandle",
+    "NotFoundError",
+    "Operation",
+    "PaymentRequiredError",
+    "PermissionDeniedError",
+    "Port",
+    "RateLimitError",
+    "ServerError",
+    "Snapshot",
+    "Spec",
+    "Template",
+    "TimeoutExceededError",
+    "ToolPolicy",
+    "UploadUrl",
+    "Usage",
+    "__version__",
+]

instabox/_base.py

@@ -0,0 +1,67 @@
+"""Shared internals: headers, options and small helpers used by both clients."""
+
+from __future__ import annotations
+
+import typing as t
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+DEFAULT_BASE_URL = "https://api.instabox.sh"
+LONG_POLL_SECONDS = "25s"  # max allowed by GET /v1/operations?wait=
+UPLOAD_LIMIT_BYTES = 5 * 1024 * 1024 * 1024  # 5 GiB
+
+
+@dataclass(frozen=True)
+class ClientOptions:
+    """Common configuration shared by the sync and async clients."""
+
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+    timeout: float = 60.0
+    default_headers: dict[str, str] | None = None
+
+
+def new_idempotency_key() -> str:
+    """Generate a fresh idempotency key (any unique string works)."""
+    return str(uuid.uuid4())
+
+
+def build_headers(api_key: str, extra: dict[str, str] | None = None) -> dict[str, str]:
+    """Build authentication and content headers for a request."""
+    headers = {"X-API-Key": api_key, "Content-Type": "application/json"}
+    if extra:
+        headers.update(extra)
+    return headers
+
+
+def json_body(data: dict[str, Any] | None) -> dict[str, Any]:
+    """Drop ``None`` values from a request body so omitted fields stay unchanged."""
+    return {k: v for k, v in (data or {}).items() if v is not None}
+
+
+def parse_sse(lines: t.Iterable[str]) -> t.Iterator[tuple[str, str]]:
+    """Parse a ``text/event-stream`` into ``(event, data)`` pairs.
+
+    Handles multi-line ``data:`` payloads (joined with newlines), comments and
+    blank-line event separators, per the SSE specification.
+    """
+    event = ""
+    data: list[str] = []
+    for line in lines:
+        line = line.rstrip("\r")
+        if not line:
+            if data:
+                yield event or "message", "\n".join(data)
+            event, data = "", []
+            continue
+        if line.startswith(":"):
+            continue  # comment
+        field, _, value = line.partition(":")
+        value = value.lstrip(" ")
+        if field == "event":
+            event = value
+        elif field == "data":
+            data.append(value)
+    if data:
+        yield event or "message", "\n".join(data)

instabox/_policy.py

@@ -0,0 +1,142 @@
+"""SDK-level tool policy: restrict which operations a client may perform.
+
+Two layers of access control exist for InstaBox:
+
+1. **API key scopes** (server-side, authoritative): keys carry scopes such as
+   ``machines:read``, ``machines:write``, ``machines:delete``, ``images:read``
+   and ``workspace:admin``. A request outside a key's scopes fails with
+   ``403 missing_scope``. Create scoped keys in the dashboard or with
+   ``instabox keys create --scope ...``.
+
+2. **SDK tool policy** (client-side, this module): an allow/deny list of
+   operation names such as ``machines.create`` or ``machines.exec``. Use it
+   when one code path (e.g. an AI agent) shares a broader key but must not
+   touch certain operations — the SDK raises
+   :class:`instabox.exceptions.PermissionDeniedError` before any network
+   request is made.
+
+Operation names follow ``<resource>.<method>``: ``machines.*``,
+``operations.*``, ``snapshots.*``, ``ports.*``, ``account.*``, plus
+``machines.ssh_tokens.*``, ``machines.secrets.*`` and ``orgs.secrets.*``
+aliases for the nested resources.
+"""
+
+from __future__ import annotations
+
+import builtins
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from .exceptions import PermissionDeniedError
+
+# Nested namespaces that are checked as their own prefix, in addition to the
+# resource class name under which they live.
+_ALIASES = {
+    "SshTokens": "machines.ssh_tokens",
+    "MachineSecrets": "machines.secrets",
+    "OrgSecrets": "orgs.secrets",
+}
+
+_POLICY_ATTR = "_instabox_policy_prefix"
+
+
+def operation_name(resource_class_name: str, method_name: str) -> str:
+    """Return the dotted operation name for a resource method."""
+    base = resource_class_name.lstrip("_")
+    if base.startswith("Async"):
+        base = base[len("Async") :]
+    prefix = _ALIASES.get(resource_class_name, base.lower())
+    return f"{prefix}.{method_name}"
+
+
+def check_allowed(policy: ToolPolicy | None, name: str) -> None:
+    """Raise :class:`PermissionDeniedError` if the policy disallows ``name``."""
+    if policy is not None and not policy.allows(name):
+        raise PermissionDeniedError(
+            status=403,
+            code="sdk_not_allowed",
+            message=(
+                f"operation '{name}' is blocked by this client's tool policy "
+                f"(allowed: {builtins.sorted(policy.allow) or '<none>'})"
+            ),
+        )
+
+
+class ToolPolicy:
+    """Allow/deny list of operation names (``resource.method`` strings).
+
+    Args:
+        allow: If given, only these operations (or prefixes ending in ``.*``)
+            are permitted. ``None`` means everything is allowed unless denied.
+        deny: Operations (or prefixes) always forbidden; wins over ``allow``.
+
+    Example::
+
+        policy = ToolPolicy(
+            allow=["machines.exec", "machines.read_file", "operations.*"],
+            deny=["machines.delete"],
+        )
+        client = Client(api_key=key, policy=policy)
+    """
+
+    __slots__ = ("allow", "deny")
+
+    def __init__(
+        self,
+        allow: builtins.set[str] | builtins.list[str] | None = None,
+        deny: builtins.set[str] | builtins.list[str] | None = None,
+    ) -> None:
+        self.allow: frozenset[str] = frozenset(allow or ())
+        self.deny: frozenset[str] = frozenset(deny or ())
+
+    def _match(self, names: frozenset[str], name: str) -> bool:
+        if name in names:
+            return True
+        prefix = name + "."
+        return any(n.endswith(".*") and prefix.startswith(n[:-1]) for n in names)
+
+    def allows(self, name: str) -> bool:
+        if self._match(self.deny, name):
+            return False
+        if not self.allow:  # nothing specified -> allow all (minus deny)
+            return True
+        return self._match(self.allow, name)
+
+
+def wrap_resource_methods(resource: Any) -> None:
+    """Wrap each public method of ``resource`` with a policy check.
+
+    The operation name is derived from the resource class name and the method
+    name; the check runs before any request is made.
+    """
+    cls = resource.__class__
+    if getattr(cls, "_policy_wrapped", False):
+        return
+    cls._policy_wrapped = True
+    prefix = operation_name(cls.__name__, "")
+    for attr, value in vars(cls).items():
+        if attr.startswith("_") or not inspect.isfunction(value):
+            continue
+        name = f"{prefix}{attr}"
+
+        def make_wrapper(func: Callable[..., Any], op_name: str) -> Callable[..., Any]:
+            def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+                check_allowed(getattr(self, "_policy", None), op_name)
+                return func(self, *args, **kwargs)
+
+            if inspect.iscoroutinefunction(func):
+
+                async def async_wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+                    check_allowed(getattr(self, "_policy", None), op_name)
+                    return await func(self, *args, **kwargs)
+
+                async_wrapper.__name__ = func.__name__
+                async_wrapper.__doc__ = func.__doc__
+                return async_wrapper
+
+            wrapper.__name__ = func.__name__
+            wrapper.__doc__ = func.__doc__
+            return wrapper
+
+        setattr(cls, attr, make_wrapper(value, name))