getstack 0.10.0__tar.gz → 0.11.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: getstack
-Version: 0.10.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.10.0 → getstack-0.11.0}/pyproject.toml

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

{getstack-0.10.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

{getstack-0.10.0 → getstack-0.11.0}/src/getstack/_async/partner_tenants.py

@@ -76,3 +76,42 @@ class AsyncPartnerTenantsService:
             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.10.0 → getstack-0.11.0}/src/getstack/partner_tenants.py

@@ -81,3 +81,49 @@ class PartnerTenantsService:
             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