getstack 0.2.0__tar.gz → 0.4.0__tar.gz

{getstack-0.2.0 → getstack-0.4.0}/CLAUDE.md

@@ -15,7 +15,6 @@ Published to PyPI as `getstack`. Not a workspace member of the main monorepo
 
 - Package metadata: `sdk-python/pyproject.toml`
 - Module entry: `sdk-python/src/getstack/`
-- Tests: `sdk-python/tests/`
 - User-facing quickstart + examples: `sdk-python/README.md`
 - License: `sdk-python/LICENSE`
 

{getstack-0.2.0 → getstack-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: getstack
-Version: 0.2.0
+Version: 0.4.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
@@ -19,7 +19,9 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.9
+Requires-Dist: cryptography>=42.0.0
 Requires-Dist: httpx>=0.25.0
+Requires-Dist: pyjwt>=2.8.0
 Description-Content-Type: text/markdown
 
 # getstack
@@ -34,16 +36,30 @@ pip install getstack
 
 ## Quick start
 
+Sign in once on your machine — the SDK reads credentials from `~/.stack/credentials.json` automatically:
+
+```bash
+npx -y @getstackrun/cli auth login
+```
+
 ```python
 from getstack import Stack
 
-stack = Stack(api_key="sk_live_...")
+# Zero-arg constructor reads ~/.stack/credentials.json (OAuth refresh token).
+# Falls back to STACK_API_KEY env var, then constructor api_key= for CI.
+stack = Stack()
 
-# Register an agent
+# 1. Register an agent (one-time)
 agent = stack.agents.register("my-agent", accountability_mode="enforced")
 
-# Run a mission with automatic checkpoints and checkout
-with stack.passports.mission(
+# 2. In your agent runtime, switch to per-agent keypair mode
+agent_stack = Stack(agent_id=agent.id)
+# First run: generates an Ed25519 keypair locally + enrolls the public
+# half via /v1/agents/<id>/enroll. Persisted at ~/.stack/agents/<id>.json
+# (mode 0600). Every subsequent call signs a fresh 60-second JWT.
+
+# 3. Run a mission with automatic checkpoints and checkout
+with agent_stack.passports.mission(
     agent_id=agent.id,
     intent="Process invoices from Slack",
     services=["slack", "stripe"],
@@ -57,22 +73,26 @@ with stack.passports.mission(
 
 ## Authentication
 
+Four sources, resolved in priority order:
+
 ```python
-# API key (most common)
-stack = Stack(api_key="sk_live_...")
+# 1. Explicit auth strategy
+stack = Stack.from_oauth(client_id="...", client_secret="", access_token="...", refresh_token="...")
+stack = Stack.from_session(session_token="...")
 
-# OAuth with auto-refresh
-stack = Stack.from_oauth(
-    client_id="...",
-    client_secret="...",
-    access_token="...",
-    refresh_token="...",
-)
+# 2. agent_id (Phase 2 — recommended for production runtimes)
+stack = Stack(agent_id="agt_xxx")
 
-# Session JWT (dashboard integrations)
-stack = Stack.from_session(session_token="...")
+# 3. api_key (legacy sk_live_*; for CI without a browser)
+stack = Stack(api_key="sk_live_...")
+# or set STACK_API_KEY in the environment
+
+# 4. ~/.stack/credentials.json (Phase 1 — `stack-cli auth login` writes it)
+stack = Stack()
 ```
 
+See [/docs/security/stack-auth](https://getstack.run/docs/security/stack-auth) for the full auth model and [/docs/security/agent-keys](https://getstack.run/docs/security/agent-keys) for the per-agent keypair story.
+
 ## Continuous missions (24/7 agents)
 
 ```python

{getstack-0.2.0 → getstack-0.4.0}/README.md

@@ -10,16 +10,30 @@ pip install getstack
 
 ## Quick start
 
+Sign in once on your machine — the SDK reads credentials from `~/.stack/credentials.json` automatically:
+
+```bash
+npx -y @getstackrun/cli auth login
+```
+
 ```python
 from getstack import Stack
 
-stack = Stack(api_key="sk_live_...")
+# Zero-arg constructor reads ~/.stack/credentials.json (OAuth refresh token).
+# Falls back to STACK_API_KEY env var, then constructor api_key= for CI.
+stack = Stack()
 
-# Register an agent
+# 1. Register an agent (one-time)
 agent = stack.agents.register("my-agent", accountability_mode="enforced")
 
-# Run a mission with automatic checkpoints and checkout
-with stack.passports.mission(
+# 2. In your agent runtime, switch to per-agent keypair mode
+agent_stack = Stack(agent_id=agent.id)
+# First run: generates an Ed25519 keypair locally + enrolls the public
+# half via /v1/agents/<id>/enroll. Persisted at ~/.stack/agents/<id>.json
+# (mode 0600). Every subsequent call signs a fresh 60-second JWT.
+
+# 3. Run a mission with automatic checkpoints and checkout
+with agent_stack.passports.mission(
     agent_id=agent.id,
     intent="Process invoices from Slack",
     services=["slack", "stripe"],
@@ -33,22 +47,26 @@ with stack.passports.mission(
 
 ## Authentication
 
+Four sources, resolved in priority order:
+
 ```python
-# API key (most common)
-stack = Stack(api_key="sk_live_...")
+# 1. Explicit auth strategy
+stack = Stack.from_oauth(client_id="...", client_secret="", access_token="...", refresh_token="...")
+stack = Stack.from_session(session_token="...")
 
-# OAuth with auto-refresh
-stack = Stack.from_oauth(
-    client_id="...",
-    client_secret="...",
-    access_token="...",
-    refresh_token="...",
-)
+# 2. agent_id (Phase 2 — recommended for production runtimes)
+stack = Stack(agent_id="agt_xxx")
 
-# Session JWT (dashboard integrations)
-stack = Stack.from_session(session_token="...")
+# 3. api_key (legacy sk_live_*; for CI without a browser)
+stack = Stack(api_key="sk_live_...")
+# or set STACK_API_KEY in the environment
+
+# 4. ~/.stack/credentials.json (Phase 1 — `stack-cli auth login` writes it)
+stack = Stack()
 ```
 
+See [/docs/security/stack-auth](https://getstack.run/docs/security/stack-auth) for the full auth model and [/docs/security/agent-keys](https://getstack.run/docs/security/agent-keys) for the per-agent keypair story.
+
 ## Continuous missions (24/7 agents)
 
 ```python

{getstack-0.2.0 → getstack-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "getstack"
-version = "0.2.0"
+version = "0.4.0"
 description = "Python SDK for STACK — trust infrastructure for AI agents"
 readme = "README.md"
 license = "MIT"
@@ -24,6 +24,14 @@ classifiers = [
 ]
 dependencies = [
     "httpx>=0.25.0",
+    # Phase 2 — agent-keypair runtime needs Ed25519 sign + verify and
+    # JWT mint. cryptography is the de-facto standalone Ed25519 lib in
+    # the Python ecosystem; ~10MB install. Pinned to a major to avoid
+    # surprise breakage but minor floats.
+    "cryptography>=42.0.0",
+    # PyJWT for agent JWT minting; pure-Python, tiny (~50KB), no native
+    # deps beyond cryptography (which we already need).
+    "pyjwt>=2.8.0",
 ]
 
 [project.urls]

{getstack-0.2.0 → getstack-0.4.0}/src/getstack/__init__.py

@@ -33,7 +33,10 @@ For async usage::
 
 from __future__ import annotations
 
-from .auth import ApiKeyAuth, SessionAuth, OAuthAuth
+import os
+
+from .auth import ApiKeyAuth, SessionAuth, OAuthAuth, CredentialsFileAuth
+from .agent_auth import AgentKeypairAuth
 from .client import HttpClient, AsyncHttpClient, DEFAULT_BASE_URL
 from .agents import AgentService
 from .passports import PassportService, Mission
@@ -80,6 +83,48 @@ from .errors import (
 
 __version__ = "0.2.0"
 
+
+def _build_static_auth(
+    *,
+    api_key: str | None,
+    base_url: str,
+) -> ApiKeyAuth | CredentialsFileAuth:
+    """Phase 2 helper. Resolve a static-bearer auth strategy for the
+    one-time agent-enrollment dance — explicit api_key, STACK_API_KEY
+    env var, or ~/.stack/credentials.json (CLI-managed OAuth refresh).
+    """
+    if api_key:
+        return ApiKeyAuth(api_key)
+    env_key = os.environ.get("STACK_API_KEY")
+    if env_key:
+        return ApiKeyAuth(env_key)
+    return _resolve_creds_or_bootstrap(base_url)
+
+
+def _resolve_creds_or_bootstrap(base_url: str) -> CredentialsFileAuth:
+    """Read ~/.stack/credentials.json — and if it's missing AND the
+    process looks interactive (TTY + not CI), spawn the browser-spawn
+    OAuth bootstrap to create it. Raises ValueError when neither path
+    resolves.
+    """
+    try:
+        return CredentialsFileAuth(api_base_url=base_url)
+    except RuntimeError:
+        from .browser_bootstrap import browser_bootstrap, should_run_browser_bootstrap
+        if should_run_browser_bootstrap():
+            browser_bootstrap(base_url)
+            try:
+                return CredentialsFileAuth(api_base_url=base_url)
+            except RuntimeError as e:
+                raise ValueError(
+                    "STACK SDK: browser bootstrap reported success but "
+                    "credentials file still missing."
+                ) from e
+        raise ValueError(
+            "No STACK credentials found. Pass api_key=, set "
+            "STACK_API_KEY, or run `stack-cli auth login`."
+        )
+
 __all__ = [
     "Stack",
     "AsyncStack",
@@ -129,16 +174,31 @@ class Stack:
         self,
         api_key: str | None = None,
         *,
+        agent_id: str | None = None,
         base_url: str = DEFAULT_BASE_URL,
         timeout: float = 30.0,
-        _auth: ApiKeyAuth | SessionAuth | OAuthAuth | None = None,
+        _auth: ApiKeyAuth | SessionAuth | OAuthAuth | CredentialsFileAuth | AgentKeypairAuth | None = None,
     ):
+        # Four-source resolution, in priority order:
+        #   1. Explicit _auth (callers that pre-built a strategy).
+        #   2. agent_id (Phase 2 — agent-keypair runtime mode). Static
+        #      bearer is auto-resolved for enrollment via api_key/env/file.
+        #   3. api_key arg or STACK_API_KEY env var (legacy sk_live_*).
+        #   4. ~/.stack/credentials.json — OAuth refresh token written
+        #      by `stack-cli auth login`.
         if _auth:
-            auth = _auth
-        elif api_key:
-            auth = ApiKeyAuth(api_key)
+            auth: ApiKeyAuth | SessionAuth | OAuthAuth | CredentialsFileAuth | AgentKeypairAuth = _auth
+        elif agent_id:
+            static_auth = _build_static_auth(api_key=api_key, base_url=base_url)
+            auth = AgentKeypairAuth(
+                agent_id=agent_id,
+                api_base_url=base_url,
+                bearer_provider=lambda: static_auth.get_headers()["Authorization"].split(" ", 1)[1],
+            )
+        elif api_key or os.environ.get("STACK_API_KEY"):
+            auth = ApiKeyAuth(api_key or os.environ["STACK_API_KEY"])
         else:
-            raise ValueError("Either api_key or _auth must be provided")
+            auth = _resolve_creds_or_bootstrap(base_url)
 
         self._client = HttpClient(auth, base_url=base_url, timeout=timeout)
         self.agents = AgentService(self._client)
@@ -209,16 +269,25 @@ class AsyncStack:
         self,
         api_key: str | None = None,
         *,
+        agent_id: str | None = None,
         base_url: str = DEFAULT_BASE_URL,
         timeout: float = 30.0,
-        _auth: ApiKeyAuth | SessionAuth | OAuthAuth | None = None,
+        _auth: ApiKeyAuth | SessionAuth | OAuthAuth | CredentialsFileAuth | AgentKeypairAuth | None = None,
     ):
+        # Same four-source resolution as Stack — see Stack.__init__.
         if _auth:
-            auth = _auth
-        elif api_key:
-            auth = ApiKeyAuth(api_key)
+            auth: ApiKeyAuth | SessionAuth | OAuthAuth | CredentialsFileAuth | AgentKeypairAuth = _auth
+        elif agent_id:
+            static_auth = _build_static_auth(api_key=api_key, base_url=base_url)
+            auth = AgentKeypairAuth(
+                agent_id=agent_id,
+                api_base_url=base_url,
+                bearer_provider=lambda: static_auth.get_headers()["Authorization"].split(" ", 1)[1],
+            )
+        elif api_key or os.environ.get("STACK_API_KEY"):
+            auth = ApiKeyAuth(api_key or os.environ["STACK_API_KEY"])
         else:
-            raise ValueError("Either api_key or _auth must be provided")
+            auth = _resolve_creds_or_bootstrap(base_url)
 
         self._client = AsyncHttpClient(auth, base_url=base_url, timeout=timeout)
 

getstack-0.4.0/src/getstack/agent_auth.py

@@ -0,0 +1,331 @@
+"""Phase 2 — agent-keypair runtime auth (Python).
+
+Mirror of packages/sdk/src/agent-auth.ts. When ``Stack(agent_id=...)`` is
+constructed, the SDK enters agent-runtime mode: every request is signed
+with a fresh 60-second EdDSA JWT minted from the agent's local privkey
+at ~/.stack/agents/<agent_id>.json.
+
+First run: open the dashboard /sdk-bootstrap page in the user's browser
+for explicit approval (interactive only — TTY + not CI), generate the
+Ed25519 keypair locally, sign the API's challenge, POST /enroll with
+the operator-approved enrollment ticket as Bearer. Persist privkey
+locally (mode 0600). Subsequent runs read from disk.
+
+Headless / CI runs (no TTY, or STACK_AUTH_INTERACTIVE=false) skip the
+browser step and fall through to the developer's OAuth bearer (or
+sk_live_* via STACK_API_KEY) for silent enrollment — same endpoints,
+same proof-of-possession, no human in the loop.
+"""
+
+from __future__ import annotations
+
+import base64
+import http.server
+import json
+import os
+import secrets
+import socket
+import socketserver
+import sys
+import threading
+import time
+import urllib.parse
+import webbrowser
+from pathlib import Path
+from typing import Callable
+
+import httpx
+import jwt
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    NoEncryption,
+    PrivateFormat,
+    PublicFormat,
+)
+
+from .auth import AuthStrategy
+from .browser_bootstrap import should_run_browser_bootstrap
+
+AGENT_JWT_TTL = 60
+AGENT_JWT_ISSUER = "stack-sdk"
+AGENT_JWT_AUDIENCE = "stack:agent"
+
+ENROLLMENT_AUTH_TIMEOUT_S = 5 * 60  # matches enrollment-ticket TTL
+
+
+def _dashboard_url(api_base_url: str) -> str:
+    """Origin to which the SDK opens the browser for the approval screen.
+
+    Override via STACK_DASHBOARD_URL for self-hosted/test environments.
+    Dev shortcut: api on localhost ⇒ dashboard on :3100.
+    """
+    override = os.environ.get("STACK_DASHBOARD_URL")
+    if override:
+        return override
+    if api_base_url.startswith(("http://127.0.0.1", "http://localhost")):
+        return "http://localhost:3100"
+    return "https://getstack.run"
+
+
+def _ticket_via_browser_approval(agent_id: str, api_base_url: str) -> str:
+    """Spawn a one-shot loopback HTTP listener, open the dashboard
+    /sdk-bootstrap page in the user's browser, and return the ticket
+    once the user approves. Raises RuntimeError on deny / timeout / any
+    failure — caller decides whether to surface or fall back.
+    """
+    state = base64.urlsafe_b64encode(secrets.token_bytes(16)).rstrip(b"=").decode("ascii")
+    machine = socket.gethostname()[:80]
+    proc_label = f"python {Path(sys.argv[0]).name}"[:80] if sys.argv else "python"
+
+    holder: dict[str, object | None] = {"ticket": None, "error": None}
+    handler_event = threading.Event()
+
+    class Handler(http.server.BaseHTTPRequestHandler):
+        def do_GET(self):  # noqa: N802
+            parsed = urllib.parse.urlparse(self.path)
+            if parsed.path != "/cb":
+                self.send_response(404)
+                self.end_headers()
+                return
+            params = urllib.parse.parse_qs(parsed.query)
+            cb_state = params.get("state", [None])[0]
+            err = params.get("error", [None])[0]
+            ticket = params.get("ticket", [None])[0]
+            if cb_state != state:
+                holder["error"] = "state mismatch"
+                self.send_response(400)
+                self.send_header("Content-Type", "text/html")
+                self.end_headers()
+                self.wfile.write(b"<html><body style='font-family:system-ui;padding:40px'><h1>State mismatch</h1></body></html>")
+            elif err:
+                holder["error"] = err
+                self.send_response(403)
+                self.send_header("Content-Type", "text/html")
+                self.end_headers()
+                self.wfile.write(b"<html><body style='font-family:system-ui;padding:40px'><h1>Enrollment denied</h1><p>You can close this tab.</p></body></html>")
+            elif not ticket:
+                holder["error"] = "missing ticket"
+                self.send_response(400)
+                self.send_header("Content-Type", "text/html")
+                self.end_headers()
+                self.wfile.write(b"<html><body style='font-family:system-ui;padding:40px'><h1>Missing ticket</h1></body></html>")
+            else:
+                holder["ticket"] = ticket
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html")
+                self.end_headers()
+                self.wfile.write(b"<html><body style='font-family:system-ui;padding:40px;text-align:center'><h1>Approved</h1><p>You can close this tab and return to your terminal.</p></body></html>")
+            handler_event.set()
+
+        def log_message(self, *_a, **_kw):
+            return
+
+    server = socketserver.TCPServer(("127.0.0.1", 0), Handler)
+    port = server.server_address[1]
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+
+    try:
+        callback = f"http://127.0.0.1:{port}/cb"
+        dash = _dashboard_url(api_base_url)
+        url = f"{dash}/sdk-bootstrap?" + urllib.parse.urlencode({
+            "agent_id": agent_id,
+            "callback": callback,
+            "state": state,
+            "machine": machine,
+            "process": proc_label,
+        })
+
+        sys.stderr.write("\n  STACK SDK agent enrollment\n")
+        sys.stderr.write("  ──────────────────────────\n\n")
+        sys.stderr.write(f"  Approve in your browser: {url}\n\n")
+
+        try:
+            webbrowser.open(url)
+        except Exception:
+            pass
+
+        if not handler_event.wait(timeout=ENROLLMENT_AUTH_TIMEOUT_S):
+            raise RuntimeError("enrollment approval timed out (5 min). Re-run to try again.")
+        if holder["error"]:
+            raise RuntimeError(f"enrollment {holder['error']}")
+        ticket = holder["ticket"]
+        if not isinstance(ticket, str):
+            raise RuntimeError("enrollment callback produced no ticket")
+        return ticket
+    finally:
+        server.shutdown()
+        server.server_close()
+
+
+def _b64url_no_pad(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _key_path(agent_id: str) -> Path:
+    return Path(os.path.expanduser("~")) / ".stack" / "agents" / f"{agent_id}.json"
+
+
+def _load_stored(agent_id: str) -> dict | None:
+    path = _key_path(agent_id)
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _persist_stored(agent_id: str, payload: dict) -> None:
+    path = _key_path(agent_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2), encoding="utf8")
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        # Windows / unsupported FS — ignore.
+        pass
+
+
+def _generate_keypair() -> tuple[Ed25519PrivateKey, dict, dict]:
+    """Generate an Ed25519 keypair and return (privkey_obj, public_jwk,
+    private_jwk_with_d)."""
+    priv = Ed25519PrivateKey.generate()
+    pub = priv.public_key()
+    pub_raw = pub.public_bytes(Encoding.Raw, PublicFormat.Raw)
+    priv_raw = priv.private_bytes(Encoding.Raw, PrivateFormat.Raw, NoEncryption())
+    public_jwk = {"kty": "OKP", "crv": "Ed25519", "x": _b64url_no_pad(pub_raw)}
+    private_jwk = {**public_jwk, "d": _b64url_no_pad(priv_raw)}
+    return priv, public_jwk, private_jwk
+
+
+def _privkey_from_jwk(jwk: dict) -> Ed25519PrivateKey:
+    pad = "=" * (-len(jwk["d"]) % 4)
+    raw = base64.urlsafe_b64decode(jwk["d"] + pad)
+    return Ed25519PrivateKey.from_private_bytes(raw)
+
+
+def _enroll(
+    agent_id: str,
+    base_url: str,
+    bearer_provider: Callable[[], str],
+) -> dict:
+    """Run the proof-of-possession enrollment dance. Returns the stored
+    payload (with private JWK) ready to persist.
+
+    Two paths converge on the same /enrollment-challenge + /enroll calls:
+
+      - Interactive: open the dashboard /sdk-bootstrap page in the user's
+        browser, get a single-use enrollment ticket, use it as the bearer.
+      - Headless: call ``bearer_provider`` (developer's OAuth or
+        STACK_API_KEY) directly. No browser, no human in the loop.
+    """
+    if should_run_browser_bootstrap():
+        try:
+            bearer = _ticket_via_browser_approval(agent_id, base_url)
+        except RuntimeError as e:
+            raise RuntimeError(
+                f"Browser approval for SDK agent enrollment failed ({e}). "
+                f"Either fix the issue and re-run, or set STACK_API_KEY "
+                f"(or STACK_AUTH_INTERACTIVE=false) to use the silent "
+                f"enrollment path."
+            ) from e
+    else:
+        bearer = bearer_provider()
+    base = base_url.rstrip("/")
+
+    # Step 1 — request challenge.
+    r = httpx.post(
+        f"{base}/v1/agents/{agent_id}/enrollment-challenge",
+        headers={"Authorization": f"Bearer {bearer}", "Content-Type": "application/json"},
+        timeout=15.0,
+    )
+    r.raise_for_status()
+    challenge_body = r.json()
+    challenge: str = challenge_body["challenge"]
+    challenge_id: str = challenge_body["challenge_id"]
+
+    # Step 2 — generate keypair locally.
+    priv_obj, public_jwk, private_jwk = _generate_keypair()
+
+    # Step 3 — sign the challenge bytes.
+    sig = priv_obj.sign(challenge.encode("utf8"))
+    signed_challenge = _b64url_no_pad(sig)
+
+    # Step 4 — POST /enroll.
+    r2 = httpx.post(
+        f"{base}/v1/agents/{agent_id}/enroll",
+        headers={"Authorization": f"Bearer {bearer}", "Content-Type": "application/json"},
+        json={
+            "public_key": public_jwk,
+            "challenge_id": challenge_id,
+            "signed_challenge": signed_challenge,
+        },
+        timeout=15.0,
+    )
+    r2.raise_for_status()
+    enrolled = r2.json()
+
+    return {
+        "agent_id": agent_id,
+        "publicKey": public_jwk,
+        "privateKey": private_jwk,
+        "enrolled_at": enrolled.get("enrolled_at"),
+    }
+
+
+def _sign_agent_jwt(stored: dict, agent_id: str) -> str:
+    """Mint a fresh 60-second EdDSA JWT signed with the agent privkey."""
+    priv_obj = _privkey_from_jwk(stored["privateKey"])
+    now = int(time.time())
+    payload = {
+        "iss": AGENT_JWT_ISSUER,
+        "sub": agent_id,
+        "aud": AGENT_JWT_AUDIENCE,
+        "iat": now,
+        "nbf": now,
+        "exp": now + AGENT_JWT_TTL,
+        "jti": f"aj_{now}_{os.urandom(6).hex()}",
+    }
+    # PyJWT accepts a raw cryptography Ed25519 key when algorithm='EdDSA'.
+    return jwt.encode(payload, priv_obj, algorithm="EdDSA")
+
+
+class AgentKeypairAuth(AuthStrategy):
+    """Phase 2 agent-runtime auth strategy.
+
+    Constructed with an agent_id and a fallback bearer provider (used
+    only for the one-time enrollment dance). Once enrolled, every
+    request mints a fresh 60-second JWT signed by the locally-stored
+    privkey — the bearer provider is no longer consulted.
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        api_base_url: str,
+        bearer_provider: Callable[[], str],
+    ):
+        self.agent_id = agent_id
+        self.api_base_url = api_base_url
+        self.bearer_provider = bearer_provider
+        self._stored: dict | None = None
+
+    def _ensure_stored(self) -> dict:
+        if self._stored is not None:
+            return self._stored
+        stored = _load_stored(self.agent_id)
+        if stored is None:
+            stored = _enroll(self.agent_id, self.api_base_url, self.bearer_provider)
+            _persist_stored(self.agent_id, stored)
+        self._stored = stored
+        return stored
+
+    def get_headers(self) -> dict[str, str]:
+        stored = self._ensure_stored()
+        token = _sign_agent_jwt(stored, self.agent_id)
+        return {"Authorization": f"Bearer {token}"}

getstack-0.4.0/src/getstack/auth.py

@@ -0,0 +1,157 @@
+"""Authentication strategies for the STACK SDK."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+import httpx
+
+
+class AuthStrategy(ABC):
+    """Base class for auth strategies."""
+
+    @abstractmethod
+    def get_headers(self) -> dict[str, str]:
+        """Return auth headers for API requests."""
+        ...
+
+
+class ApiKeyAuth(AuthStrategy):
+    """Authenticate with a STACK API key (sk_live_...)."""
+
+    def __init__(self, api_key: str):
+        self.api_key = api_key
+
+    def get_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+
+class SessionAuth(AuthStrategy):
+    """Authenticate with a session JWT (dashboard integrations)."""
+
+    def __init__(self, session_token: str):
+        self.session_token = session_token
+
+    def get_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.session_token}"}
+
+
+class OAuthAuth(AuthStrategy):
+    """Authenticate with OAuth tokens. Auto-refreshes when expired.
+
+    For OAuth 2.1 public PKCE clients (the Phase 1 default), pass
+    ``client_secret=""``. The token endpoint accepts public clients with
+    no secret.
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        access_token: str,
+        refresh_token: str,
+        token_endpoint: str = "https://api.getstack.run/oauth/token",
+    ):
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.access_token = access_token
+        self.refresh_token = refresh_token
+        self.token_endpoint = token_endpoint
+        self.expires_at: float | None = None
+
+    def get_headers(self) -> dict[str, str]:
+        if self.expires_at and time.time() > self.expires_at - 30:
+            self._refresh()
+        return {"Authorization": f"Bearer {self.access_token}"}
+
+    def _refresh(self) -> None:
+        """Exchange refresh_token for a new access_token."""
+        body: dict[str, str] = {
+            "grant_type": "refresh_token",
+            "refresh_token": self.refresh_token,
+            "client_id": self.client_id,
+        }
+        if self.client_secret:
+            body["client_secret"] = self.client_secret
+        resp = httpx.post(self.token_endpoint, data=body)
+        resp.raise_for_status()
+        data = resp.json()
+        self.access_token = data["access_token"]
+        self.refresh_token = data.get("refresh_token", self.refresh_token)
+        self.expires_at = time.time() + data.get("expires_in", 300)
+
+
+class CredentialsFileAuth(AuthStrategy):
+    """Read OAuth credentials from ~/.stack/credentials.json.
+
+    Mirror of the TS SDK's lazy refresh-from-file path. The CLI's
+    ``stack-cli auth login`` (Device flow) writes this file; both SDKs
+    read it. On every request we exchange the stored refresh for a fresh
+    access token (5-minute TTL, rotation-on-use), then cache it in
+    memory until 30 seconds before expiry.
+
+    Raises ``FileNotFoundError`` (re-raised as ``RuntimeError``) on
+    construction if the file is missing — callers should fall back to
+    ``ApiKeyAuth`` from ``STACK_API_KEY`` first.
+    """
+
+    def __init__(
+        self,
+        credentials_path: Path | None = None,
+        api_base_url: str = "https://api.getstack.run",
+    ):
+        self.path = credentials_path or (Path(os.path.expanduser("~")) / ".stack" / "credentials.json")
+        self.token_endpoint = f"{api_base_url.rstrip('/')}/oauth/token"
+        if not self.path.exists():
+            raise RuntimeError(
+                f"No STACK credentials at {self.path}. "
+                "Run `stack-cli auth login` or set STACK_API_KEY."
+            )
+        self._load()
+        self._access_token: str | None = None
+        self._access_expires_at: float = 0.0
+
+    def _load(self) -> None:
+        with self.path.open("r", encoding="utf8") as f:
+            data = json.load(f)
+        self.client_id: str = data["client_id"]
+        self.refresh_token: str = data["refresh_token"]
+        self.scope: str = data.get("scope", "")
+
+    def _refresh(self) -> None:
+        resp = httpx.post(
+            self.token_endpoint,
+            data={
+                "grant_type": "refresh_token",
+                "refresh_token": self.refresh_token,
+                "client_id": self.client_id,
+            },
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        self._access_token = data["access_token"]
+        self._access_expires_at = time.time() + data.get("expires_in", 300)
+        self.refresh_token = data.get("refresh_token", self.refresh_token)
+        # Persist the rotated refresh.
+        try:
+            current = json.loads(self.path.read_text(encoding="utf8"))
+            current["refresh_token"] = self.refresh_token
+            current["issued_at"] = int(time.time())
+            current["refresh_expires_at"] = int(time.time()) + 30 * 24 * 60 * 60
+            self.path.write_text(json.dumps(current, indent=2), encoding="utf8")
+            try:
+                os.chmod(self.path, 0o600)
+            except OSError:
+                pass
+        except OSError:
+            pass
+
+    def get_headers(self) -> dict[str, str]:
+        if not self._access_token or time.time() > self._access_expires_at - 30:
+            self._refresh()
+        assert self._access_token is not None
+        return {"Authorization": f"Bearer {self._access_token}"}

getstack-0.4.0/src/getstack/browser_bootstrap.py

@@ -0,0 +1,212 @@
+"""Phase 1 SDK first-run browser-spawn bootstrap (Python).
+
+Mirror of packages/sdk/src/browser-bootstrap.ts. When ``Stack()`` is
+constructed with no api_key, no STACK_API_KEY env, and no
+~/.stack/credentials.json — instead of raising, the SDK can spawn the
+user's browser and run the OAuth Authorization Code + PKCE dance
+itself.
+
+Triggered ONLY when the process is interactive (TTY + not CI). In
+production agent runtimes (Lambda, Vercel, K8s) the SDK falls through
+to the standard "no credentials" error and the operator must set
+STACK_API_KEY (or use agent_id mode).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import http.server
+import json
+import os
+import secrets
+import socket
+import socketserver
+import sys
+import threading
+import time
+import urllib.parse
+import webbrowser
+from pathlib import Path
+
+import httpx
+
+DEFAULT_AUTH_TIMEOUT_S = 5 * 60  # matches the auth-code TTL
+
+
+def _credentials_path() -> Path:
+    return Path(os.path.expanduser("~")) / ".stack" / "credentials.json"
+
+
+def _b64url_no_pad(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def should_run_browser_bootstrap() -> bool:
+    """Conservative gate: only spawn if we're at an interactive terminal."""
+    if not sys.stdout.isatty():
+        return False
+    if os.environ.get("STACK_AUTH_INTERACTIVE", "").lower() == "false":
+        return False
+    if os.environ.get("CI"):
+        return False
+    return True
+
+
+def browser_bootstrap(base_url: str) -> dict:
+    """Run the full OAuth Authorization-Code + PKCE flow.
+
+    Returns ``{"access_token", "refresh_token", "expires_in", "client_id"}``.
+    Raises RuntimeError on any step failure.
+    """
+    base = base_url.rstrip("/")
+
+    # 1. DCR a public PKCE client. We re-register with the loopback URI
+    #    once we know the bound port (DCR is open; the second register
+    #    supersedes for redirect_uri matching).
+    name = f"STACK Python SDK on {socket.gethostname()[:40]}"
+
+    # 2. Pick a free port + spin up the callback server first, so we can
+    #    register the client with the actual loopback URI.
+    code_holder: dict = {"code": None, "error": None, "expected_state": None}
+    handler_event = threading.Event()
+
+    class Handler(http.server.BaseHTTPRequestHandler):
+        def do_GET(self):  # noqa: N802
+            parsed = urllib.parse.urlparse(self.path)
+            if parsed.path != "/callback":
+                self.send_response(404)
+                self.end_headers()
+                return
+            params = urllib.parse.parse_qs(parsed.query)
+            err = params.get("error", [None])[0]
+            code = params.get("code", [None])[0]
+            state = params.get("state", [None])[0]
+            if err:
+                code_holder["error"] = err
+                self.send_response(400)
+                self.send_header("Content-Type", "text/html")
+                self.end_headers()
+                self.wfile.write(b"<html><body style='font-family:system-ui;padding:40px'><h1>Sign-in failed</h1><p>You can close this tab.</p></body></html>")
+            elif not code or state != code_holder["expected_state"]:
+                code_holder["error"] = "invalid callback (state mismatch or missing code)"
+                self.send_response(400)
+                self.send_header("Content-Type", "text/html")
+                self.end_headers()
+                self.wfile.write(b"<html><body style='font-family:system-ui;padding:40px'><h1>Invalid callback</h1></body></html>")
+            else:
+                code_holder["code"] = code
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html")
+                self.end_headers()
+                self.wfile.write(b"<html><body style='font-family:system-ui;padding:40px;text-align:center'><h1>Signed in</h1><p>You can close this tab and return to your terminal.</p></body></html>")
+            handler_event.set()
+
+        def log_message(self, *_args, **_kwargs):
+            return  # silence access logs
+
+    # Bind to port 0 to get a free port.
+    server = socketserver.TCPServer(("127.0.0.1", 0), Handler)
+    port = server.server_address[1]
+    server_thread = threading.Thread(target=server.serve_forever, daemon=True)
+    server_thread.start()
+
+    try:
+        redirect_uri = f"http://127.0.0.1:{port}/callback"
+
+        # DCR with the actual loopback URI.
+        r = httpx.post(
+            f"{base}/oauth/register",
+            json={
+                "client_name": name,
+                "redirect_uris": [redirect_uri],
+                "grant_types": ["authorization_code", "refresh_token"],
+                "software_id": "getstackrun.sdk-python.bootstrap",
+            },
+            timeout=15.0,
+        )
+        if r.status_code != 201:
+            raise RuntimeError(
+                f"STACK SDK: client registration failed ({r.status_code}). "
+                f"Try setting STACK_API_KEY or running `stack-cli auth login`."
+            )
+        client_id = r.json()["client_id"]
+
+        # 3. PKCE pair + state.
+        verifier = _b64url_no_pad(secrets.token_bytes(32))
+        challenge = _b64url_no_pad(hashlib.sha256(verifier.encode()).digest())
+        state = _b64url_no_pad(secrets.token_bytes(16))
+        code_holder["expected_state"] = state
+
+        scope = "passports:read passports:write agents:read agents:write services:read services:connect credentials:read proxy:read proxy:write audit:read"
+        authorize_url = f"{base}/oauth/authorize?" + urllib.parse.urlencode({
+            "response_type": "code",
+            "client_id": client_id,
+            "redirect_uri": redirect_uri,
+            "scope": scope,
+            "resource": "https://api.getstack.run",
+            "code_challenge": challenge,
+            "code_challenge_method": "S256",
+            "state": state,
+        })
+
+        sys.stderr.write("\n  STACK SDK first-run sign-in\n")
+        sys.stderr.write("  ──────────────────────────\n\n")
+        sys.stderr.write("  Opening your browser to approve.\n")
+        sys.stderr.write(f"  If it doesn't open, paste this URL:\n\n  {authorize_url}\n\n")
+
+        try:
+            webbrowser.open(authorize_url)
+        except Exception:
+            pass  # best-effort
+
+        # 4. Wait for the callback.
+        if not handler_event.wait(timeout=DEFAULT_AUTH_TIMEOUT_S):
+            raise RuntimeError("Sign-in timed out (5 min). Re-run to try again.")
+        if code_holder["error"]:
+            raise RuntimeError(f"OAuth error: {code_holder['error']}")
+        code = code_holder["code"]
+
+        # 5. Exchange code for tokens.
+        r2 = httpx.post(
+            f"{base}/oauth/token",
+            data={
+                "grant_type": "authorization_code",
+                "code": code,
+                "redirect_uri": redirect_uri,
+                "client_id": client_id,
+                "code_verifier": verifier,
+            },
+            timeout=15.0,
+        )
+        if r2.status_code != 200:
+            raise RuntimeError(f"STACK SDK: token exchange failed ({r2.status_code}) {r2.text}")
+        tokens = r2.json()
+
+        # 6. Persist for subsequent runs. Same file the CLI + the TS SDK write.
+        path = _credentials_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        stored = {
+            "client_id": client_id,
+            "refresh_token": tokens["refresh_token"],
+            "issued_at": int(time.time()),
+            "refresh_expires_at": int(time.time()) + 30 * 24 * 60 * 60,
+            "scope": scope,
+        }
+        path.write_text(json.dumps(stored, indent=2), encoding="utf8")
+        try:
+            os.chmod(path, 0o600)
+        except OSError:
+            pass
+
+        sys.stderr.write(f"  Signed in. Credentials saved to {path}\n\n")
+
+        return {
+            "access_token": tokens["access_token"],
+            "refresh_token": tokens["refresh_token"],
+            "expires_in": tokens.get("expires_in", 300),
+            "client_id": client_id,
+        }
+    finally:
+        server.shutdown()
+        server.server_close()

getstack-0.2.0/src/getstack/auth.py

@@ -1,78 +0,0 @@
-"""Authentication strategies for the STACK SDK."""
-
-from __future__ import annotations
-
-import time
-from abc import ABC, abstractmethod
-
-import httpx
-
-
-class AuthStrategy(ABC):
-    """Base class for auth strategies."""
-
-    @abstractmethod
-    def get_headers(self) -> dict[str, str]:
-        """Return auth headers for API requests."""
-        ...
-
-
-class ApiKeyAuth(AuthStrategy):
-    """Authenticate with a STACK API key (sk_live_...)."""
-
-    def __init__(self, api_key: str):
-        self.api_key = api_key
-
-    def get_headers(self) -> dict[str, str]:
-        return {"Authorization": f"Bearer {self.api_key}"}
-
-
-class SessionAuth(AuthStrategy):
-    """Authenticate with a session JWT (dashboard integrations)."""
-
-    def __init__(self, session_token: str):
-        self.session_token = session_token
-
-    def get_headers(self) -> dict[str, str]:
-        return {"Authorization": f"Bearer {self.session_token}"}
-
-
-class OAuthAuth(AuthStrategy):
-    """Authenticate with OAuth tokens. Auto-refreshes when expired."""
-
-    def __init__(
-        self,
-        client_id: str,
-        client_secret: str,
-        access_token: str,
-        refresh_token: str,
-        token_endpoint: str = "https://api.getstack.run/v1/oauth/token",
-    ):
-        self.client_id = client_id
-        self.client_secret = client_secret
-        self.access_token = access_token
-        self.refresh_token = refresh_token
-        self.token_endpoint = token_endpoint
-        self.expires_at: float | None = None
-
-    def get_headers(self) -> dict[str, str]:
-        if self.expires_at and time.time() > self.expires_at - 30:
-            self._refresh()
-        return {"Authorization": f"Bearer {self.access_token}"}
-
-    def _refresh(self) -> None:
-        """Exchange refresh_token for a new access_token."""
-        resp = httpx.post(
-            self.token_endpoint,
-            data={
-                "grant_type": "refresh_token",
-                "refresh_token": self.refresh_token,
-                "client_id": self.client_id,
-                "client_secret": self.client_secret,
-            },
-        )
-        resp.raise_for_status()
-        data = resp.json()
-        self.access_token = data["access_token"]
-        self.refresh_token = data.get("refresh_token", self.refresh_token)
-        self.expires_at = time.time() + data.get("expires_in", 3600)