safe-colab 0.19.0__tar.gz

safe_colab-0.19.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: safe-colab
+Version: 0.19.0
+Summary: CLI tool for safe collaboration - sandboxed Jupyter kernel with remote Hypha service access
+Author: Amun AI AB
+License: All Rights Reserved
+Project-URL: Homepage, https://safe-colab.amun.ai
+Project-URL: Guardian, https://guard.amun.ai
+Keywords: safe-colab,sandbox,jupyter,hypha,remote-execution
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: hypha-rpc>=0.20.0
+Requires-Dist: jupyter_client>=8.0
+Requires-Dist: ipykernel>=6.0
+Requires-Dist: click>=8.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: nono-py>=0.1.0; sys_platform != "win32"
+Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=1.24
+Provides-Extra: desktop
+Requires-Dist: aiohttp>=3.9; extra == "desktop"
+Provides-Extra: sandbox
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-timeout>=2.0; extra == "dev"
+Requires-Dist: pytest-aiohttp>=1.0; extra == "dev"
+Requires-Dist: aiohttp>=3.9; extra == "dev"
+Requires-Dist: pyyaml>=6.0; extra == "dev"
+Provides-Extra: e2e
+Requires-Dist: hypha[s3]>=0.21; extra == "e2e"
+Requires-Dist: pytest>=8.0; extra == "e2e"
+Requires-Dist: pytest-asyncio>=0.23; extra == "e2e"
+Requires-Dist: httpx>=0.24.0; extra == "e2e"
+
+# Safe Colab CLI
+
+**Enable AI agents to analyze your sensitive data remotely — without ever copying it.**
+
+A command-line tool that launches a sandboxed Python environment on your machine (or in the cloud), registers it as a remote service via [Hypha](https://hypha.amun.ai), and lets AI agents execute code through a guardian agent that enforces your sensitivity policy.
+
+## Key Features
+
+- **Guardian Agent** — LLM-powered security checks validate code before execution and output before return
+- **Sensitivity Contract** — Define protected columns, minimum aggregation, and allowed operations in a README.md
+- **Live Dashboard** — Web dashboard with real-time activity log and operation stats
+- **Protected Audit Logs** — Full audit trail in `~/.safe-colab/logs/`, protected from sandboxed code
+- **Sandbox Isolation** — nono (macOS/Linux) or Docker restricts kernel filesystem access
+- **Remote Hosting** — Upload dataset once, cloud pods spin up on demand (no laptop needed)
+- **Zero Config for Agents** — Agents call `get_skill_md` via curl to learn the API. No SDK, no token needed.
+
+## Quick Start
+
+### Local Mode (data stays on your machine)
+
+```bash
+pip install safe-colab-cli
+safe-colab login --server-url https://hypha.amun.ai
+safe-colab start --data-dir ./my-data --guardian-url https://guard.amun.ai
+```
+
+### Remote Mode (upload once, pods on demand)
+
+```bash
+pip install safe-colab-cli
+safe-colab login --server-url https://hypha.amun.ai
+safe-colab deploy --data-dir ./my-data --guardian-url https://guard.amun.ai
+# → Uploads dataset, registers app. Share the App ID with your AI agent.
+# → Pods spin up automatically when an agent calls start().
+```
+
+### Use the Amun AI production servers
+
+Safe Colab talks to **two** services and both must point at the Amun AI
+deployment (older installs and some docs default to an `aicell.io` instance):
+
+| Service | Amun AI URL | How to set it |
+|---------|-------------|---------------|
+| **Hypha** (registers your kernel; chosen at **login**) | `https://hypha.amun.ai` | `safe-colab login --server-url https://hypha.amun.ai` |
+| **Guardian** (validates every code/output) | `https://guard.amun.ai` | `--guardian-url https://guard.amun.ai` on `start`/`deploy` |
+
+The Hypha server is fixed **at login time** — if you logged in against a
+different server, re-run `safe-colab login --server-url https://hypha.amun.ai`
+to overwrite the saved credentials in `~/.safe-colab/.env`. You can also set
+both via environment (persist them in your shell profile):
+
+```bash
+export HYPHA_SERVER_URL=https://hypha.amun.ai
+export SAFE_COLAB_GUARDIAN_URL=https://guard.amun.ai
+```
+
+Verify the guardian before a session or demo (accepts the Terms of Use, then
+runs a built-in safe/blocked suite):
+
+```bash
+safe-colab test-guardian --url https://guard.amun.ai --accept-terms
+# → Health: OK … 4/4 tests passed
+```
+
+## Documentation
+
+See the [docs site](https://aicell-lab.github.io/safe-colab-cli/) or the [GitHub project](https://github.com/aicell-lab/safe-colab-cli) for full documentation.
+
+## License
+
+Copyright 2024-2026 Amun AI AB. All rights reserved.
+
+This software is proprietary and confidential. No part of this software may be reproduced, distributed, or transmitted in any form or by any means without the prior written permission of Amun AI AB. Unauthorized copying, modification, distribution, or use of this software is strictly prohibited.

safe_colab-0.19.0/README.md

@@ -0,0 +1,73 @@
+# Safe Colab CLI
+
+**Enable AI agents to analyze your sensitive data remotely — without ever copying it.**
+
+A command-line tool that launches a sandboxed Python environment on your machine (or in the cloud), registers it as a remote service via [Hypha](https://hypha.amun.ai), and lets AI agents execute code through a guardian agent that enforces your sensitivity policy.
+
+## Key Features
+
+- **Guardian Agent** — LLM-powered security checks validate code before execution and output before return
+- **Sensitivity Contract** — Define protected columns, minimum aggregation, and allowed operations in a README.md
+- **Live Dashboard** — Web dashboard with real-time activity log and operation stats
+- **Protected Audit Logs** — Full audit trail in `~/.safe-colab/logs/`, protected from sandboxed code
+- **Sandbox Isolation** — nono (macOS/Linux) or Docker restricts kernel filesystem access
+- **Remote Hosting** — Upload dataset once, cloud pods spin up on demand (no laptop needed)
+- **Zero Config for Agents** — Agents call `get_skill_md` via curl to learn the API. No SDK, no token needed.
+
+## Quick Start
+
+### Local Mode (data stays on your machine)
+
+```bash
+pip install safe-colab-cli
+safe-colab login --server-url https://hypha.amun.ai
+safe-colab start --data-dir ./my-data --guardian-url https://guard.amun.ai
+```
+
+### Remote Mode (upload once, pods on demand)
+
+```bash
+pip install safe-colab-cli
+safe-colab login --server-url https://hypha.amun.ai
+safe-colab deploy --data-dir ./my-data --guardian-url https://guard.amun.ai
+# → Uploads dataset, registers app. Share the App ID with your AI agent.
+# → Pods spin up automatically when an agent calls start().
+```
+
+### Use the Amun AI production servers
+
+Safe Colab talks to **two** services and both must point at the Amun AI
+deployment (older installs and some docs default to an `aicell.io` instance):
+
+| Service | Amun AI URL | How to set it |
+|---------|-------------|---------------|
+| **Hypha** (registers your kernel; chosen at **login**) | `https://hypha.amun.ai` | `safe-colab login --server-url https://hypha.amun.ai` |
+| **Guardian** (validates every code/output) | `https://guard.amun.ai` | `--guardian-url https://guard.amun.ai` on `start`/`deploy` |
+
+The Hypha server is fixed **at login time** — if you logged in against a
+different server, re-run `safe-colab login --server-url https://hypha.amun.ai`
+to overwrite the saved credentials in `~/.safe-colab/.env`. You can also set
+both via environment (persist them in your shell profile):
+
+```bash
+export HYPHA_SERVER_URL=https://hypha.amun.ai
+export SAFE_COLAB_GUARDIAN_URL=https://guard.amun.ai
+```
+
+Verify the guardian before a session or demo (accepts the Terms of Use, then
+runs a built-in safe/blocked suite):
+
+```bash
+safe-colab test-guardian --url https://guard.amun.ai --accept-terms
+# → Health: OK … 4/4 tests passed
+```
+
+## Documentation
+
+See the [docs site](https://aicell-lab.github.io/safe-colab-cli/) or the [GitHub project](https://github.com/aicell-lab/safe-colab-cli) for full documentation.
+
+## License
+
+Copyright 2024-2026 Amun AI AB. All rights reserved.
+
+This software is proprietary and confidential. No part of this software may be reproduced, distributed, or transmitted in any form or by any means without the prior written permission of Amun AI AB. Unauthorized copying, modification, distribution, or use of this software is strictly prohibited.

safe_colab-0.19.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "safe-colab"
+version = "0.19.0"
+description = "CLI tool for safe collaboration - sandboxed Jupyter kernel with remote Hypha service access"
+readme = "README.md"
+license = {text = "All Rights Reserved"}
+requires-python = ">=3.9"
+authors = [{name = "Amun AI AB"}]
+keywords = ["safe-colab", "sandbox", "jupyter", "hypha", "remote-execution"]
+dependencies = [
+    "hypha-rpc>=0.20.0",
+    "jupyter_client>=8.0",
+    "ipykernel>=6.0",
+    "click>=8.0",
+    "python-dotenv>=1.0",
+    "httpx>=0.24.0",
+    "aiohttp>=3.9",
+    "nono-py>=0.1.0; sys_platform != 'win32'",
+    # Data-science packages so the served analysis kernel can actually do work
+    # (the product is for analyzing tabular data; without these every query fails
+    # with ModuleNotFoundError on a fresh install).
+    "pandas>=2.0",
+    "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+desktop = [
+    "aiohttp>=3.9",
+]
+sandbox = [
+]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "pytest-timeout>=2.0",
+    "pytest-aiohttp>=1.0",
+    "aiohttp>=3.9",
+    "pyyaml>=6.0",
+]
+# Hermetic full-journey E2E (cli/tests/e2e): boots a LOCAL Hypha server + mock
+# LLM + the real Guardian (see tests/e2e/hermetic_infra.py) and drives the real
+# owner-serve → analyst-run journey end to end. `hypha[s3]` provides the
+# `python -m hypha.server` the harness launches.
+e2e = [
+    "hypha[s3]>=0.21",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "httpx>=0.24.0",
+]
+
+[project.urls]
+Homepage = "https://safe-colab.amun.ai"
+Guardian = "https://guard.amun.ai"
+
+[project.scripts]
+safe-colab = "safe_colab.cli:main"
+safe-colab-daemon = "safe_colab.daemon:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["safe_colab*"]
+
+[tool.setuptools.package-data]
+safe_colab = ["*.html"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "slow: marks tests that require micromamba and network access",
+    "sandbox: filesystem-isolation tests that run a real nono sandbox and assert enforcement; require a privileged sandbox runtime, not a generic CI runner",
+]

safe_colab-0.19.0/safe_colab/__init__.py

@@ -0,0 +1,3 @@
+"""Safe Colab CLI - Sandboxed Jupyter kernel with remote Hypha service access."""
+
+__version__ = "0.19.0"

safe_colab-0.19.0/safe_colab/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as python -m safe_colab."""
+from .cli import main
+
+main()

safe_colab-0.19.0/safe_colab/artifacts.py

@@ -0,0 +1,255 @@
+"""Artifact manager integration for file sharing, logging, and auditing.
+
+Creates a collection per user and a child artifact per session.
+Files (plots, results, large datasets) are uploaded to the artifact manager
+and shared via presigned URLs - no data copying needed.
+"""
+
+import os
+import time
+import json
+import hashlib
+import secrets
+import logging
+from datetime import datetime, timezone
+from typing import Optional
+
+import httpx
+
+logger = logging.getLogger("safe_colab.artifacts")
+
+COLLECTION_ALIAS = "safe-colab-sessions"
+
+# Hypha rejects artifact aliases longer than 64 characters. A session_id minted
+# with secrets.token_hex(32) is 64 hex chars, so the naive f"session-{id}" alias
+# is 72 chars and the artifact fails to create — silently disabling file sharing
+# and the audit log. Clamp defensively at the single construction chokepoint.
+MAX_ALIAS_LEN = 64
+_ALIAS_PREFIX = "session-"
+
+
+def session_alias(session_id: str) -> str:
+    """A valid (<=64 char), stable, collision-resistant alias for a session.
+
+    Short ids are used verbatim (`session-<id>`). When the full alias would
+    exceed Hypha's 64-char cap, we hash the WHOLE session_id — a prefix slice
+    would collide for ids that share a prefix — into a 48-char sha-256 digest,
+    keeping 192 bits of entropy well under the limit.
+    """
+    alias = f"{_ALIAS_PREFIX}{session_id}"
+    if len(alias) <= MAX_ALIAS_LEN:
+        return alias
+    digest = hashlib.sha256(session_id.encode("utf-8")).hexdigest()[:48]
+    return f"{_ALIAS_PREFIX}{digest}"
+
+
+class SessionArtifactManager:
+    """Manages artifacts for a single safe-colab session.
+
+    Creates a collection (if needed) and a session artifact within it.
+    Provides upload/download via presigned URLs and audit logging.
+    """
+
+    def __init__(self, artifact_manager, session_id: str, workspace: str, server_url: str = "https://hypha.amun.ai"):
+        self._am = artifact_manager
+        self.session_id = session_id
+        self.workspace = workspace
+        self.server_url = server_url.rstrip("/")
+        self.collection_id = None
+        self.artifact_id = None
+        self.artifact_alias = None
+        self.view_base_url = None
+        self._log_buffer = []
+
+    async def initialize(self):
+        """Create the collection (idempotent) and session artifact."""
+        # Ensure collection exists
+        try:
+            collection = await self._am.read(artifact_id=COLLECTION_ALIAS)
+            self.collection_id = collection["id"]
+        except Exception:
+            collection = await self._am.create(
+                type="collection",
+                alias=COLLECTION_ALIAS,
+                manifest={
+                    "name": "Safe Colab Sessions",
+                    "description": "Collection of safe-colab session artifacts for auditing and file sharing",
+                },
+                config={
+                    "permissions": {"*": "r", "@": "rw+"},
+                },
+                stage=True,
+            )
+            self.collection_id = collection["id"]
+            try:
+                await self._am.commit(self.collection_id)
+            except Exception:
+                pass  # Already committed or no staging needed
+
+        # Create session artifact with static hosting enabled
+        self.artifact_alias = session_alias(self.session_id)
+        artifact = await self._am.create(
+            type="dataset",
+            alias=self.artifact_alias,
+            parent_id=self.collection_id,
+            manifest={
+                "name": f"Session {self.session_id[:8]}",
+                "description": f"Safe Colab session started at {datetime.now(timezone.utc).isoformat()}",
+                "session_id": self.session_id,
+                "created_at": datetime.now(timezone.utc).isoformat(),
+            },
+            config={
+                "permissions": {"*": "r", "@": "rw+"},
+                "view_config": {
+                    "templates": [],
+                },
+            },
+            stage=True,
+        )
+        self.artifact_id = artifact["id"]
+        self.view_base_url = f"{self.server_url}/{self.workspace}/view/{self.artifact_alias}"
+        logger.info(f"Session artifact created: {self.artifact_id}")
+        logger.info(f"View URL: {self.view_base_url}/")
+
+        # Write initial audit log entry
+        await self.log_event("session_start", {"session_id": self.session_id})
+
+    async def upload_file(
+        self,
+        local_path: str,
+        remote_path: Optional[str] = None,
+        data: Optional[bytes] = None,
+    ) -> dict:
+        """Upload a file and return a permanent view URL.
+
+        The file is uploaded to the session artifact which has static hosting
+        enabled. The returned URL renders in the browser (HTML/images) rather
+        than triggering a download.
+
+        Args:
+            local_path: Local file path to upload (used for the remote name
+                default and the audit-log entry).
+            remote_path: Path within the artifact (defaults to filename).
+            data: When provided, the EXACT bytes to upload — the caller has
+                already read (and, for safe-colab, Guardian-audited) them. This
+                avoids an independent second read of ``local_path``: re-reading
+                the path here would ship whatever the file holds at upload time,
+                not what was audited, opening a TOCTOU on the one channel that
+                ships bytes off-box (#0308). When ``None`` the legacy path-read is
+                used (no auditing caller).
+
+        Returns:
+            Dict with 'view_url' (permanent, renders in browser) and
+            'download_url' (presigned S3, expires in 1h).
+        """
+        if remote_path is None:
+            remote_path = os.path.basename(local_path)
+
+        # Re-enter staging mode if already committed (allows multiple uploads)
+        try:
+            await self._am.edit(artifact_id=self.artifact_id, stage=True)
+        except Exception:
+            pass  # May already be in staging
+
+        put_url = await self._am.put_file(self.artifact_id, file_path=remote_path)
+
+        # Ship the caller-supplied (Guardian-audited) buffer verbatim; only fall
+        # back to reading the path when no buffer was given (#0308).
+        if data is None:
+            with open(local_path, "rb") as f:
+                data = f.read()
+
+        async with httpx.AsyncClient() as client:
+            resp = await client.put(put_url, content=data)
+            resp.raise_for_status()
+
+        # Commit so the file is visible via /view/
+        try:
+            await self._am.commit(self.artifact_id)
+        except Exception:
+            pass  # May already be committed
+
+        view_url = f"{self.view_base_url}/{remote_path}"
+        download_url = await self._am.get_file(self.artifact_id, file_path=remote_path)
+
+        await self.log_event("file_upload", {
+            "local_path": local_path,
+            "remote_path": remote_path,
+            "size_bytes": len(data),
+            "view_url": view_url,
+        })
+
+        return {"view_url": view_url, "download_url": download_url}
+
+    async def upload_bytes(self, data: bytes, remote_path: str, content_type: str = "application/octet-stream") -> str:
+        """Upload raw bytes and return a presigned download URL."""
+        put_url = await self._am.put_file(self.artifact_id, file_path=remote_path)
+
+        async with httpx.AsyncClient() as client:
+            resp = await client.put(put_url, content=data, headers={"Content-Type": content_type})
+            resp.raise_for_status()
+
+        get_url = await self._am.get_file(self.artifact_id, file_path=remote_path)
+
+        await self.log_event("bytes_upload", {
+            "remote_path": remote_path,
+            "size_bytes": len(data),
+            "content_type": content_type,
+        })
+
+        return get_url
+
+    async def get_download_url(self, remote_path: str) -> str:
+        """Get a presigned download URL for an existing file."""
+        return await self._am.get_file(self.artifact_id, file_path=remote_path)
+
+    async def list_files(self) -> list:
+        """List all files in the session artifact."""
+        return await self._am.list_files(self.artifact_id)
+
+    async def log_event(self, event_type: str, details: dict):
+        """Append an audit log entry to the session artifact."""
+        entry = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "event": event_type,
+            **details,
+        }
+        self._log_buffer.append(entry)
+
+        # Write log file
+        log_content = "\n".join(json.dumps(e) for e in self._log_buffer) + "\n"
+        try:
+            try:
+                await self._am.edit(artifact_id=self.artifact_id, stage=True)
+            except Exception:
+                pass
+            put_url = await self._am.put_file(self.artifact_id, file_path="audit_log.jsonl")
+            async with httpx.AsyncClient() as client:
+                await client.put(put_url, content=log_content.encode())
+        except Exception as e:
+            logger.warning(f"Failed to write audit log: {e}")
+
+    async def log_code_execution(self, code: str, result: dict):
+        """Log a code execution event for auditing."""
+        await self.log_event("code_execution", {
+            "code_length": len(code),
+            "code_preview": code[:200] + ("..." if len(code) > 200 else ""),
+            "has_error": result.get("error") is not None,
+            "stdout_length": len(result.get("stdout", "")),
+        })
+
+    async def log_command_execution(self, command: str, result: dict):
+        """Log a shell command execution event."""
+        await self.log_event("command_execution", {
+            "command": command[:200],
+            "returncode": result.get("returncode"),
+        })
+
+    async def commit(self, version: Optional[str] = None):
+        """Commit the session artifact (makes files permanent)."""
+        await self._am.commit(
+            self.artifact_id,
+            version=version,
+            comment=f"Session {self.session_id[:8]} committed",
+        )
+        logger.info(f"Session artifact committed: {self.artifact_id}")

safe_colab-0.19.0/safe_colab/auth.py

@@ -0,0 +1,147 @@
+"""Authentication and credential management.
+
+Stores credentials in ~/.safe-colab/.env (or $SAFE_COLAB_HOME/.env).
+Supports interactive Hypha login with browser-based OAuth.
+"""
+
+import os
+import re
+import json
+import base64
+import time
+from pathlib import Path
+from typing import Optional
+
+
+def get_config_dir() -> Path:
+    """Get the safe-colab config directory (~/.safe-colab/)."""
+    home = os.environ.get("SAFE_COLAB_HOME", os.path.join(Path.home(), ".safe-colab"))
+    return Path(home)
+
+
+def get_credentials_path() -> Path:
+    """Get the credentials file path."""
+    return get_config_dir() / ".env"
+
+
+def save_credentials(server_url: str, token: str, workspace: str):
+    """Save credentials to ~/.safe-colab/.env"""
+    config_dir = get_config_dir()
+    config_dir.mkdir(parents=True, exist_ok=True)
+    cred_path = get_credentials_path()
+
+    # Read existing lines, preserve non-credential entries
+    existing = {}
+    if cred_path.exists():
+        for line in cred_path.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            if "=" in line:
+                key, val = line.split("=", 1)
+                existing[key.strip()] = val.strip()
+
+    existing["HYPHA_SERVER_URL"] = server_url
+    existing["HYPHA_TOKEN"] = token
+    existing["HYPHA_WORKSPACE"] = workspace
+
+    lines = [f"{k}={v}" for k, v in existing.items()]
+    content = "\n".join(lines) + "\n"
+    # Write atomically with restrictive permissions from the start
+    fd = os.open(str(cred_path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        os.write(fd, content.encode())
+    finally:
+        os.close(fd)
+    return cred_path
+
+
+def load_credentials() -> dict:
+    """Load credentials from ~/.safe-colab/.env
+
+    Returns dict with keys: server_url, token, workspace (any may be None).
+    """
+    result = {"server_url": None, "token": None, "workspace": None}
+
+    cred_path = get_credentials_path()
+    if not cred_path.exists():
+        return result
+
+    for line in cred_path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, val = line.split("=", 1)
+        key = key.strip()
+        val = val.strip().strip("\"'")
+
+        if key == "HYPHA_SERVER_URL":
+            result["server_url"] = val
+        elif key == "HYPHA_TOKEN":
+            result["token"] = val
+        elif key == "HYPHA_WORKSPACE":
+            result["workspace"] = val
+
+    # Validate token expiry
+    if result["token"] and is_token_expired(result["token"]):
+        result["token"] = None
+
+    return result
+
+
+def decode_token(token: str) -> Optional[dict]:
+    """Decode JWT payload without verification (for extracting claims)."""
+    try:
+        parts = token.split(".")
+        if len(parts) != 3:
+            return None
+        payload_b64 = parts[1]
+        # Add padding
+        pad = len(payload_b64) % 4
+        if pad:
+            payload_b64 += "=" * (4 - pad)
+        # JWTs are base64URL-encoded (RFC 7515): the alphabet uses - and _ , not
+        # +/. base64.b64decode silently DROPS -/_ then raises, so a valid token
+        # whose payload carries a base64url -/_ decodes to None here -> the user
+        # is wrongly logged out (is_token_expired -> True). Must use urlsafe.
+        # (#0158)
+        return json.loads(base64.urlsafe_b64decode(payload_b64))
+    except Exception:
+        return None
+
+
+def is_token_expired(token: str) -> bool:
+    """Check if a JWT token has expired."""
+    payload = decode_token(token)
+    if not payload:
+        return True
+    exp = payload.get("exp")
+    if not exp:
+        return False
+    return time.time() > exp
+
+
+def extract_workspace_from_token(token: str) -> Optional[str]:
+    """Extract workspace ID from token's scope claim."""
+    payload = decode_token(token)
+    if not payload:
+        return None
+    scope = payload.get("scope", "")
+    # Match patterns like "ws:my-workspace#rw" or "wid:my-workspace"
+    m = re.search(r"ws:([\w\-|]+)#", scope)
+    if m:
+        return m.group(1)
+    m = re.search(r"wid:([\w\-|]+)", scope)
+    if m:
+        return m.group(1)
+    return None
+
+
+def extract_email_from_token(token: str) -> Optional[str]:
+    """Extract email from token claims."""
+    payload = decode_token(token)
+    if not payload:
+        return None
+    return payload.get("https://amun.ai/email")