getstack 0.9.0__tar.gz → 0.11.0__tar.gz

{getstack-0.9.0 → getstack-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: getstack
-Version: 0.9.0
+Version: 0.11.0
 Summary: Python SDK for STACK — trust infrastructure for AI agents
 Project-URL: Homepage, https://getstack.run
 Project-URL: Documentation, https://getstack.run/docs/sdk

{getstack-0.9.0 → getstack-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "getstack"
-version = "0.9.0"
+version = "0.11.0"
 description = "Python SDK for STACK — trust infrastructure for AI agents"
 readme = "README.md"
 license = "MIT"

{getstack-0.9.0 → getstack-0.11.0}/src/getstack/__init__.py

@@ -53,6 +53,8 @@ from .security_events import SecurityEventService as SecurityEventSvc
 from .skills import SkillService
 from .identity import IdentityService
 from .inbound_webhooks import InboundWebhookService
+from .partner_tenants import PartnerTenantsService
+from .passport_header_verify import verify_passport_header
 from .intents import IntentsService
 from .missions import MissionsService
 from .evidence_packs import EvidencePacksService
@@ -226,6 +228,7 @@ class Stack:
         self.evidence_packs = EvidencePacksService(self._client)
         self.llm = LlmService(self._client)
         self.inbound_webhooks = InboundWebhookService(self._client)
+        self.partner_tenants = PartnerTenantsService(self._client)
 
     def issue_passport(
         self,
@@ -366,6 +369,7 @@ class AsyncStack:
         from ._async.missions import AsyncMissionsService
         from ._async.llm import AsyncLlmService
         from ._async.inbound_webhooks import AsyncInboundWebhookService
+        from ._async.partner_tenants import AsyncPartnerTenantsService
         from ._async.passport_session import AsyncPassportSession
 
         self.agents = AsyncAgentService(self._client)
@@ -385,6 +389,7 @@ class AsyncStack:
         self.missions = AsyncMissionsService(self._client)
         self.llm = AsyncLlmService(self._client)
         self.inbound_webhooks = AsyncInboundWebhookService(self._client)
+        self.partner_tenants = AsyncPartnerTenantsService(self._client)
         # Stash for issue_passport() — Python doesn't easily expose the
         # class binding without re-importing inside the method body.
         self._AsyncPassportSession = AsyncPassportSession

getstack-0.11.0/src/getstack/_async/partner_tenants.py

@@ -0,0 +1,117 @@
+"""Async mirror of PartnerTenantsService (Phase 5.6)."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from ..client import AsyncHttpClient
+
+
+Tier = Literal["free", "developer", "studio", "enterprise"]
+
+
+class AsyncPartnerTenantsService:
+    def __init__(self, client: AsyncHttpClient):
+        self._client = client
+
+    async def create(
+        self,
+        external_customer_id: Optional[str] = None,
+        tier: Optional[Tier] = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {}
+        if external_customer_id is not None:
+            body["external_customer_id"] = external_customer_id
+        if tier is not None:
+            body["tier"] = tier
+        return await self._client.post("/v1/partner/tenants", json=body)
+
+    async def list(self) -> list[dict[str, Any]]:
+        res = await self._client.get("/v1/partner/tenants")
+        return list(res.get("tenants", []))
+
+    async def get(self, tenant_id: str) -> dict[str, Any]:
+        return await self._client.get(f"/v1/partner/tenants/{tenant_id}")
+
+    async def revoke(self, tenant_id: str) -> dict[str, Any]:
+        return await self._client.delete(f"/v1/partner/tenants/{tenant_id}")
+
+    async def create_inbound_webhook(
+        self,
+        tenant_id: str,
+        provider: Literal["agentmail", "generic"],
+        agent_id: str,
+        forward_url: Optional[str] = None,
+        generic_config: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"provider": provider, "agent_id": agent_id}
+        if forward_url is not None:
+            body["forward_url"] = forward_url
+        if generic_config is not None:
+            body["generic_config"] = generic_config
+        return await self._client.post(
+            f"/v1/partner/tenants/{tenant_id}/inbound-webhooks",
+            json=body,
+        )
+
+    async def issue_passport(
+        self,
+        tenant_id: str,
+        agent_id: str,
+        ttl_seconds: Optional[int] = None,
+        services: Optional[list[dict[str, Any]]] = None,
+        named_intents: Optional[list[str]] = None,
+        accountability_mode: Optional[Literal["enforced", "logged", "standard"]] = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"agent_id": agent_id}
+        if ttl_seconds is not None:
+            body["ttl_seconds"] = ttl_seconds
+        if services is not None:
+            body["services"] = services
+        if named_intents is not None:
+            body["named_intents"] = named_intents
+        if accountability_mode is not None:
+            body["accountability_mode"] = accountability_mode
+        return await self._client.post(
+            f"/v1/partner/tenants/{tenant_id}/passports/issue",
+            json=body,
+        )
+
+    async def mint_outbound_passport(
+        self,
+        tenant_id: str,
+        agent_id: str,
+        scopes: Optional[list[str]] = None,
+        ttl_seconds: int = 900,
+        accountability_mode: Literal["enforced", "logged", "standard"] = "enforced",
+        named_intents: Optional[list[str]] = None,
+    ) -> dict[str, Any]:
+        """Phase 5.7 — convenience helper for the MIME-stamping pattern.
+
+        Async mirror of PartnerTenantsService.mint_outbound_passport.
+        """
+        services = [{"scopes": scopes}] if scopes else None
+        issued = await self.issue_passport(
+            tenant_id,
+            agent_id,
+            ttl_seconds=ttl_seconds,
+            accountability_mode=accountability_mode,
+            services=services,
+            named_intents=named_intents,
+        )
+        token = issued.get("token") or issued.get("passport")
+        passport_id = issued.get("passport_id") or issued.get("jti")
+        if not token or not passport_id:
+            raise RuntimeError("mint_outbound_passport: API response missing token or passport_id")
+        expires_at = issued.get("expires_at")
+        if not expires_at:
+            exp = issued.get("exp")
+            if isinstance(exp, (int, float)):
+                from datetime import datetime, timezone
+                expires_at = datetime.fromtimestamp(exp, tz=timezone.utc).isoformat()
+        return {
+            "token": token,
+            "passport_id": passport_id,
+            "expires_at": expires_at,
+            "header_value": token,
+        }

getstack-0.11.0/src/getstack/partner_tenants.py

@@ -0,0 +1,129 @@
+"""Partner-tenancy surface (Phase 5.6).
+
+Platform partners (AgentMail, Cofounder, etc.) with is_partner=True on
+their operator row provision isolated child operators on behalf of
+their customers via this service.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from .client import HttpClient
+
+
+Tier = Literal["free", "developer", "studio", "enterprise"]
+
+
+class PartnerTenantsService:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def create(
+        self,
+        external_customer_id: Optional[str] = None,
+        tier: Optional[Tier] = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {}
+        if external_customer_id is not None:
+            body["external_customer_id"] = external_customer_id
+        if tier is not None:
+            body["tier"] = tier
+        return self._client.post("/v1/partner/tenants", json=body)
+
+    def list(self) -> list[dict[str, Any]]:
+        res = self._client.get("/v1/partner/tenants")
+        return list(res.get("tenants", []))
+
+    def get(self, tenant_id: str) -> dict[str, Any]:
+        return self._client.get(f"/v1/partner/tenants/{tenant_id}")
+
+    def revoke(self, tenant_id: str) -> dict[str, Any]:
+        return self._client.delete(f"/v1/partner/tenants/{tenant_id}")
+
+    def create_inbound_webhook(
+        self,
+        tenant_id: str,
+        provider: Literal["agentmail", "generic"],
+        agent_id: str,
+        forward_url: Optional[str] = None,
+        generic_config: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"provider": provider, "agent_id": agent_id}
+        if forward_url is not None:
+            body["forward_url"] = forward_url
+        if generic_config is not None:
+            body["generic_config"] = generic_config
+        return self._client.post(
+            f"/v1/partner/tenants/{tenant_id}/inbound-webhooks",
+            json=body,
+        )
+
+    def issue_passport(
+        self,
+        tenant_id: str,
+        agent_id: str,
+        ttl_seconds: Optional[int] = None,
+        services: Optional[list[dict[str, Any]]] = None,
+        named_intents: Optional[list[str]] = None,
+        accountability_mode: Optional[Literal["enforced", "logged", "standard"]] = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"agent_id": agent_id}
+        if ttl_seconds is not None:
+            body["ttl_seconds"] = ttl_seconds
+        if services is not None:
+            body["services"] = services
+        if named_intents is not None:
+            body["named_intents"] = named_intents
+        if accountability_mode is not None:
+            body["accountability_mode"] = accountability_mode
+        return self._client.post(
+            f"/v1/partner/tenants/{tenant_id}/passports/issue",
+            json=body,
+        )
+
+    def mint_outbound_passport(
+        self,
+        tenant_id: str,
+        agent_id: str,
+        scopes: Optional[list[str]] = None,
+        ttl_seconds: int = 900,
+        accountability_mode: Literal["enforced", "logged", "standard"] = "enforced",
+        named_intents: Optional[list[str]] = None,
+    ) -> dict[str, Any]:
+        """Phase 5.7 — convenience helper for the MIME-stamping pattern.
+
+        Mints a passport under the tenant's per-operator signing key
+        with a default-narrow scope, returning the token along with
+        the value ready for direct header injection (`X-Stack-Passport:
+        <token>`). The receiver verifies offline via verify_passport_header.
+
+        Defaults: 15-minute TTL, accountability_mode='enforced'.
+
+        Returns dict with keys: token, passport_id, expires_at, header_value.
+        """
+        services = [{"scopes": scopes}] if scopes else None
+        issued = self.issue_passport(
+            tenant_id,
+            agent_id,
+            ttl_seconds=ttl_seconds,
+            accountability_mode=accountability_mode,
+            services=services,
+            named_intents=named_intents,
+        )
+        token = issued.get("token") or issued.get("passport")
+        passport_id = issued.get("passport_id") or issued.get("jti")
+        if not token or not passport_id:
+            raise RuntimeError("mint_outbound_passport: API response missing token or passport_id")
+        expires_at = issued.get("expires_at")
+        if not expires_at:
+            exp = issued.get("exp")
+            if isinstance(exp, (int, float)):
+                from datetime import datetime, timezone
+                expires_at = datetime.fromtimestamp(exp, tz=timezone.utc).isoformat()
+        return {
+            "token": token,
+            "passport_id": passport_id,
+            "expires_at": expires_at,
+            "header_value": token,
+        }

getstack-0.11.0/src/getstack/passport_header_verify.py

@@ -0,0 +1,109 @@
+"""Partner-side helper for the X-Stack-Passport convention (Phase 5.7).
+
+Pulls the passport token from request headers (or accepts the raw
+string), looks up the issuing tenant's JWKS, and verifies offline.
+No network at verify time after first JWKS fetch per tenant.
+
+Usage:
+
+    from getstack import verify_passport_header
+
+    claims = verify_passport_header(
+        request.headers.get('x-stack-passport'),
+        base_url='https://api.getstack.run',
+    )
+    tenant_id = claims['stk']['operator_id']
+    agent_id = claims['stk']['agent_id']
+
+Does NOT check revocation. For revocation-aware verification, layer
+a short-window cache on POST /v1/passports/verify.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Union
+
+import jwt
+from jwt import PyJWKClient
+
+
+DEFAULT_BASE_URL = "https://api.getstack.run"
+DEFAULT_ISSUER = "getstack.run"
+DEFAULT_AUDIENCE = "stack:passport"
+
+# Cache PyJWKClient per JWKS URL so repeat verifies share the key cache.
+_jwks_client_cache: dict[str, PyJWKClient] = {}
+
+
+def _get_jwks_client(jwks_url: str) -> PyJWKClient:
+    client = _jwks_client_cache.get(jwks_url)
+    if client is None:
+        client = PyJWKClient(jwks_url)
+        _jwks_client_cache[jwks_url] = client
+    return client
+
+
+def verify_passport_header(
+    header_value: Optional[Union[str, list[str]]],
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+    issuer: str = DEFAULT_ISSUER,
+    audience: str = DEFAULT_AUDIENCE,
+) -> dict[str, Any]:
+    """Verify an X-Stack-Passport header value.
+
+    The header value is a STACK passport JWT signed under the issuing
+    tenant's per-operator signing key. This function decodes the JWT
+    (unverified) to read the sub claim (= tenant operator_id), resolves
+    the per-tenant JWKS URL, and verifies signature + issuer +
+    audience + expiry.
+
+    Raises ValueError on any failure — missing header, malformed JWT,
+    missing sub, signature failure, wrong issuer/audience, expired.
+    The caller should treat any raise as a 401 reject.
+
+    Returns the decoded claims dict on success.
+    """
+    if header_value is None:
+        raise ValueError("verify_passport_header: missing header value")
+    if isinstance(header_value, list):
+        if not header_value:
+            raise ValueError("verify_passport_header: header value is empty list")
+        token = header_value[0]
+    else:
+        token = header_value
+    if not isinstance(token, str) or not token:
+        raise ValueError("verify_passport_header: header value is empty")
+
+    # Decode unverified to read the tenant operator_id. The signature
+    # check that follows binds the sub to the JWKS so an attacker can't
+    # substitute a different tenant's sub.
+    try:
+        unverified = jwt.decode(token, options={"verify_signature": False})
+    except jwt.PyJWTError as err:
+        raise ValueError(f"verify_passport_header: malformed JWT ({err})") from err
+
+    tenant_id = unverified.get("sub")
+    if not tenant_id or not isinstance(tenant_id, str):
+        raise ValueError("verify_passport_header: token missing sub claim")
+
+    jwks_url = f"{base_url.rstrip('/')}/v1/operators/{tenant_id}/jwks.json"
+    jwk_client = _get_jwks_client(jwks_url)
+
+    try:
+        signing_key = jwk_client.get_signing_key_from_jwt(token)
+    except jwt.PyJWKClientError as err:
+        raise ValueError(f"verify_passport_header: jwks lookup failed ({err})") from err
+
+    try:
+        verified = jwt.decode(
+            token,
+            signing_key.key,
+            algorithms=["EdDSA"],
+            issuer=issuer,
+            audience=audience,
+        )
+    except jwt.InvalidTokenError as err:
+        raise ValueError(f"verify_passport_header: signature/claims invalid ({err})") from err
+
+    return verified