getstack 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: getstack
-Version: 0.3.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

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

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

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

@@ -98,13 +98,32 @@ def _build_static_auth(
     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 as e:
+    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(
-            "Agent enrollment needs a static bearer (api_key=, "
-            "STACK_API_KEY, or `stack-cli auth login`) — none found."
-        ) from e
+            "No STACK credentials found. Pass api_key=, set "
+            "STACK_API_KEY, or run `stack-cli auth login`."
+        )
 
 __all__ = [
     "Stack",
@@ -179,13 +198,7 @@ class Stack:
         elif api_key or os.environ.get("STACK_API_KEY"):
             auth = ApiKeyAuth(api_key or os.environ["STACK_API_KEY"])
         else:
-            try:
-                auth = CredentialsFileAuth(api_base_url=base_url)
-            except RuntimeError as e:
-                raise ValueError(
-                    "No STACK credentials found. Pass api_key=, set "
-                    "STACK_API_KEY, or run `stack-cli auth login`."
-                ) from e
+            auth = _resolve_creds_or_bootstrap(base_url)
 
         self._client = HttpClient(auth, base_url=base_url, timeout=timeout)
         self.agents = AgentService(self._client)
@@ -274,13 +287,7 @@ class AsyncStack:
         elif api_key or os.environ.get("STACK_API_KEY"):
             auth = ApiKeyAuth(api_key or os.environ["STACK_API_KEY"])
         else:
-            try:
-                auth = CredentialsFileAuth(api_base_url=base_url)
-            except RuntimeError as e:
-                raise ValueError(
-                    "No STACK credentials found. Pass api_key=, set "
-                    "STACK_API_KEY, or run `stack-cli auth login`."
-                ) from e
+            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/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.3.0/src/getstack/agent_auth.py

@@ -1,189 +0,0 @@
-"""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: generate Ed25519 keypair, request enrollment challenge from
-the API, sign challenge with privkey, POST /enroll. Persist privkey
-locally (mode 0600). Subsequent runs read from disk.
-"""
-
-from __future__ import annotations
-
-import base64
-import json
-import os
-import time
-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
-
-AGENT_JWT_TTL = 60
-AGENT_JWT_ISSUER = "stack-sdk"
-AGENT_JWT_AUDIENCE = "stack:agent"
-
-
-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."""
-    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}"}