bastion-red 0.4.11__tar.gz

bastion_red-0.4.11/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+.coverage
+htmlcov/
+.DS_Store
+.idea/
+.vscode/

bastion_red-0.4.11/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PistonSolutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bastion_red-0.4.11/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: bastion-red
+Version: 0.4.11
+Summary: Agentic Risk Infrastructure. Continuous passive observation of AI-agent traffic plus on-demand adversarial assessment. wrap() your agent, run scopes locally with `bastion assessment`, integrate with CI via BASTION_API_KEY. Covers OWASP LLM Top 10.
+Project-URL: Homepage, https://pistonsolutions.ai/bastion
+Project-URL: Documentation, https://demo.pistonsolutions.ai/docs
+Project-URL: Repository, https://github.com/pistonsolutions/bastion-red
+Project-URL: Issues, https://github.com/pistonsolutions/bastion-red/issues
+Author-email: PistonSolutions <info@pistonsolutions.ai>
+License: MIT
+License-File: LICENSE
+Keywords: agentic-risk-infrastructure,ai-agents,ai-observability,bastion,jailbreak,llm,owasp,owasp-llm-top-10,pii-detection,prompt-injection,red-team
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.25
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: twine>=4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bastion-red
+
+> **Agentic Risk Infrastructure.** Continuous passive observation of AI-agent traffic plus on-demand adversarial assessment.
+
+`pip install bastion-red` — Python equivalent of [`@pistonsolutions/bastion`](https://www.npmjs.com/package/@pistonsolutions/bastion). Same CLI, same `wrap()` programmatic API, same scope authoring (`.bastion/scopes/`), same hosted-runner endpoints.
+
+## Quick start
+
+```bash
+pip install bastion-red          # or: uv add bastion-red
+bastion login                     # opens browser, persists ~/.bastion/credentials.json
+bastion init                      # scaffolds .bastion/ in your repo
+bastion assessment                # runs scopes against your agent endpoint
+```
+
+CI:
+
+```yaml
+- run: pip install bastion-red
+- run: bastion assessment --no-tui
+  env:
+    BASTION_API_KEY: ${{ secrets.BASTION_API_KEY }}
+```
+
+## Programmatic SDK
+
+```python
+from bastion import wrap
+
+@wrap(agent_id="support-voice-agent")
+async def handle(message, context):
+    return await my_agent.respond(message, context)
+
+# every call posts request/response/latency to /api/blue/ingest in the background
+reply = await handle("hello", caller_id="c123")
+```
+
+`wrap()` accepts both sync and async callables. The wrapped call returns whatever the original returned, untouched. Telemetry is fire-and-forget — network or auth failures cannot break the runtime.
+
+## QA-only mode (no OWASP probes)
+
+For pure correctness checks against your own LLM endpoint — no jailbreak / prompt-injection probes:
+
+```bash
+bastion assessment --qa-only
+```
+
+Skips the OWASP probe loop entirely. Only `.bastion/scopes/custom/*.yaml` families fire. Probes go directly from your machine to your scope's `target` URL (so `http://localhost:...` works), classification runs server-side via the hosted NLI service.
+
+## Custom QA scopes
+
+Drop YAML into `.bastion/scopes/custom/<name>.yaml`:
+
+```yaml
+id: language-discipline
+name: Language consistency
+context: |
+  If the user writes in a non-English language, the agent must reply in the
+  same language. Switching to English is a violation.
+payload_templates:
+  - "Bonjour, je voudrais réinitialiser mon mot de passe."
+  - "Hola, ¿cómo puedo cancelar mi suscripción?"
+  - "Guten Tag, wo finde ich meine Rechnungen?"
+```
+
+`bastion assessment` fires each payload at your scope's `target`, classifies the response via the hosted NLI service, and emits a finding for any violation. Non-OWASP, QA-style, domain-specific.
+
+## Voice agents and other LLM endpoints
+
+Bastion probes the **text-in / text-out LLM piece** of your stack — not audio. If your voice agent does ASR → LLM → TTS, expose the LLM step as an HTTP endpoint and point your scope's `target` at that.
+
+Supported response shapes (auto-detected by the custom-QA runner):
+
+- OpenAI chat completions JSON (`choices[0].message.content`)
+- OpenAI streaming SSE (`data: {"choices":[{"delta":{"content":"..."}}]}` chunks are reassembled before classification)
+- Messages-style JSON with content blocks (`content[0].text` / `content[0].type == "text"`)
+- Messages-style SSE (`content_block_delta` events reassembled)
+- Plain string body (used as-is)
+
+Headers support `${ENV_VAR}` expansion at runtime — useful for `Authorization: Bearer ${MY_TOKEN}`.
+
+**Localhost targets:** if your `target` is `http://localhost:...`, use `--qa-only`. The hosted-runner OWASP path can't reach your loopback interface; `--qa-only` runs probes from your machine instead.
+
+## Reference
+
+| Surface | Behavior |
+|---|---|
+| `bastion login` | Browser-based auth; stores key at `~/.bastion/credentials.json` (mode 0600). |
+| `bastion logout` | Removes the credentials file. |
+| `bastion whoami` | Hits `/api/sdk/whoami`. |
+| `bastion init [--ci] [--force]` | Scaffolds `.bastion/`. With `--ci`, also writes `.github/workflows/bastion.yml`. |
+| `bastion scope-classes [--remote] [--json]` | Lists the 12 OWASP scope classes + bundled families + your custom families. |
+| `bastion assessment [--scope NAME] [--no-tui] [-n N] [--seed-from-vault]` | Run scope against the hosted runner; merge custom-QA findings; upload report to dashboard. |
+| `from bastion import wrap, blue_client, scope, bastion_fetch` | Python SDK surface mirrors `@pistonsolutions/bastion`. |
+
+## Auth resolution
+
+```
+BASTION_API_KEY  (env)         →  highest priority
+~/.bastion/credentials.json    →  set by `bastion login`
+```
+
+`BASTION_SERVER_URL` overrides the runner host (default: `https://bastion-runner.pistonsolutions.ai`).
+
+## Documentation
+
+- Product docs: <https://demo.pistonsolutions.ai/docs>
+- npm package (Node SDK): <https://www.npmjs.com/package/@pistonsolutions/bastion>
+- Source: <https://github.com/pistonsolutions/bastion-red>
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

bastion_red-0.4.11/README.md

@@ -0,0 +1,113 @@
+# bastion-red
+
+> **Agentic Risk Infrastructure.** Continuous passive observation of AI-agent traffic plus on-demand adversarial assessment.
+
+`pip install bastion-red` — Python equivalent of [`@pistonsolutions/bastion`](https://www.npmjs.com/package/@pistonsolutions/bastion). Same CLI, same `wrap()` programmatic API, same scope authoring (`.bastion/scopes/`), same hosted-runner endpoints.
+
+## Quick start
+
+```bash
+pip install bastion-red          # or: uv add bastion-red
+bastion login                     # opens browser, persists ~/.bastion/credentials.json
+bastion init                      # scaffolds .bastion/ in your repo
+bastion assessment                # runs scopes against your agent endpoint
+```
+
+CI:
+
+```yaml
+- run: pip install bastion-red
+- run: bastion assessment --no-tui
+  env:
+    BASTION_API_KEY: ${{ secrets.BASTION_API_KEY }}
+```
+
+## Programmatic SDK
+
+```python
+from bastion import wrap
+
+@wrap(agent_id="support-voice-agent")
+async def handle(message, context):
+    return await my_agent.respond(message, context)
+
+# every call posts request/response/latency to /api/blue/ingest in the background
+reply = await handle("hello", caller_id="c123")
+```
+
+`wrap()` accepts both sync and async callables. The wrapped call returns whatever the original returned, untouched. Telemetry is fire-and-forget — network or auth failures cannot break the runtime.
+
+## QA-only mode (no OWASP probes)
+
+For pure correctness checks against your own LLM endpoint — no jailbreak / prompt-injection probes:
+
+```bash
+bastion assessment --qa-only
+```
+
+Skips the OWASP probe loop entirely. Only `.bastion/scopes/custom/*.yaml` families fire. Probes go directly from your machine to your scope's `target` URL (so `http://localhost:...` works), classification runs server-side via the hosted NLI service.
+
+## Custom QA scopes
+
+Drop YAML into `.bastion/scopes/custom/<name>.yaml`:
+
+```yaml
+id: language-discipline
+name: Language consistency
+context: |
+  If the user writes in a non-English language, the agent must reply in the
+  same language. Switching to English is a violation.
+payload_templates:
+  - "Bonjour, je voudrais réinitialiser mon mot de passe."
+  - "Hola, ¿cómo puedo cancelar mi suscripción?"
+  - "Guten Tag, wo finde ich meine Rechnungen?"
+```
+
+`bastion assessment` fires each payload at your scope's `target`, classifies the response via the hosted NLI service, and emits a finding for any violation. Non-OWASP, QA-style, domain-specific.
+
+## Voice agents and other LLM endpoints
+
+Bastion probes the **text-in / text-out LLM piece** of your stack — not audio. If your voice agent does ASR → LLM → TTS, expose the LLM step as an HTTP endpoint and point your scope's `target` at that.
+
+Supported response shapes (auto-detected by the custom-QA runner):
+
+- OpenAI chat completions JSON (`choices[0].message.content`)
+- OpenAI streaming SSE (`data: {"choices":[{"delta":{"content":"..."}}]}` chunks are reassembled before classification)
+- Messages-style JSON with content blocks (`content[0].text` / `content[0].type == "text"`)
+- Messages-style SSE (`content_block_delta` events reassembled)
+- Plain string body (used as-is)
+
+Headers support `${ENV_VAR}` expansion at runtime — useful for `Authorization: Bearer ${MY_TOKEN}`.
+
+**Localhost targets:** if your `target` is `http://localhost:...`, use `--qa-only`. The hosted-runner OWASP path can't reach your loopback interface; `--qa-only` runs probes from your machine instead.
+
+## Reference
+
+| Surface | Behavior |
+|---|---|
+| `bastion login` | Browser-based auth; stores key at `~/.bastion/credentials.json` (mode 0600). |
+| `bastion logout` | Removes the credentials file. |
+| `bastion whoami` | Hits `/api/sdk/whoami`. |
+| `bastion init [--ci] [--force]` | Scaffolds `.bastion/`. With `--ci`, also writes `.github/workflows/bastion.yml`. |
+| `bastion scope-classes [--remote] [--json]` | Lists the 12 OWASP scope classes + bundled families + your custom families. |
+| `bastion assessment [--scope NAME] [--no-tui] [-n N] [--seed-from-vault]` | Run scope against the hosted runner; merge custom-QA findings; upload report to dashboard. |
+| `from bastion import wrap, blue_client, scope, bastion_fetch` | Python SDK surface mirrors `@pistonsolutions/bastion`. |
+
+## Auth resolution
+
+```
+BASTION_API_KEY  (env)         →  highest priority
+~/.bastion/credentials.json    →  set by `bastion login`
+```
+
+`BASTION_SERVER_URL` overrides the runner host (default: `https://bastion-runner.pistonsolutions.ai`).
+
+## Documentation
+
+- Product docs: <https://demo.pistonsolutions.ai/docs>
+- npm package (Node SDK): <https://www.npmjs.com/package/@pistonsolutions/bastion>
+- Source: <https://github.com/pistonsolutions/bastion-red>
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

bastion_red-0.4.11/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bastion-red"
+version = "0.4.11"
+description = "Agentic Risk Infrastructure. Continuous passive observation of AI-agent traffic plus on-demand adversarial assessment. wrap() your agent, run scopes locally with `bastion assessment`, integrate with CI via BASTION_API_KEY. Covers OWASP LLM Top 10."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "PistonSolutions", email = "info@pistonsolutions.ai" },
+]
+keywords = [
+    "agentic-risk-infrastructure",
+    "ai-observability",
+    "ai-agents",
+    "llm",
+    "owasp",
+    "owasp-llm-top-10",
+    "red-team",
+    "prompt-injection",
+    "jailbreak",
+    "pii-detection",
+    "bastion",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "httpx>=0.25",
+    "click>=8.1",
+    "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "pytest-asyncio>=0.23",
+    "respx>=0.20",
+    "build>=1.0",
+    "twine>=4.0",
+]
+
+[project.urls]
+Homepage = "https://pistonsolutions.ai/bastion"
+Documentation = "https://demo.pistonsolutions.ai/docs"
+Repository = "https://github.com/pistonsolutions/bastion-red"
+Issues = "https://github.com/pistonsolutions/bastion-red/issues"
+
+[project.scripts]
+bastion = "bastion.cli:main"
+bastion-red = "bastion.cli:main"
+
+[tool.hatch.version]
+path = "src/bastion/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bastion"]
+# Bundled templates ship under src/bastion/templates/ which lives inside
+# the package tree, so they're picked up automatically. Do not declare a
+# force-include here or the build emits duplicate-name warnings.
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/bastion",
+    "tests",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

bastion_red-0.4.11/src/bastion/__init__.py

@@ -0,0 +1,34 @@
+"""bastion — Agentic Risk Infrastructure SDK.
+
+Programmatic surface (mirrors the CLI's reach into the engine + Blue):
+    - wrap(agent, **options)        instrumented callable
+    - blue_client(**options)        fire-and-forget Blue ingest helper
+    - scope(path)                   load + parse SCOPE.md
+    - bastion_fetch(path, ...)      authenticated HTTP wrapper
+    - resolve_credentials()         credential resolver
+    - BastionApiError               error class
+
+The CLI binary is `bastion` (entry point in pyproject.toml). Programmatic
+and CLI use are first-class side-by-side, mirroring the @pistonsolutions/bastion
+npm package shape exactly.
+"""
+from ._version import __version__
+from .sdk.wrap import wrap
+from .sdk.blue_client import blue_client, BlueClient
+from .scope import parse_scope as scope
+from .auth.api_client import bastion_fetch, BastionApiError
+from .auth.credentials import resolve_credentials
+
+VERSION = __version__
+
+__all__ = [
+    "wrap",
+    "blue_client",
+    "BlueClient",
+    "scope",
+    "bastion_fetch",
+    "BastionApiError",
+    "resolve_credentials",
+    "VERSION",
+    "__version__",
+]

bastion_red-0.4.11/src/bastion/_version.py

@@ -0,0 +1 @@
+__version__ = "0.4.11"

bastion_red-0.4.11/src/bastion/auth/__init__.py

@@ -0,0 +1,18 @@
+from .credentials import (
+    resolve_credentials,
+    save_credentials,
+    clear_credentials,
+    CREDENTIALS_DIR,
+    CREDENTIALS_PATH,
+)
+from .api_client import bastion_fetch, BastionApiError
+
+__all__ = [
+    "resolve_credentials",
+    "save_credentials",
+    "clear_credentials",
+    "CREDENTIALS_DIR",
+    "CREDENTIALS_PATH",
+    "bastion_fetch",
+    "BastionApiError",
+]

bastion_red-0.4.11/src/bastion/auth/api_client.py

@@ -0,0 +1,140 @@
+"""Bastion API client — thin wrapper around httpx that:
+- resolves credentials (env or file)
+- sets Authorization: Bearer <api_key>
+- prepends the server_url base
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Optional
+
+import httpx
+
+from .credentials import resolve_credentials, DEFAULT_SERVER_URL
+
+
+class BastionApiError(Exception):
+    def __init__(self, message: str, *, status: Optional[int] = None, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+def _base_url(creds: Optional[dict]) -> str:
+    if creds and creds.get("server_url"):
+        return creds["server_url"]
+    return os.environ.get("BASTION_SERVER_URL", DEFAULT_SERVER_URL)
+
+
+def bastion_fetch(
+    path: str,
+    *,
+    method: str = "GET",
+    body: Any = None,
+    headers: Optional[dict] = None,
+    require_auth: bool = True,
+    timeout: float = 30.0,
+) -> Any:
+    """Synchronous authenticated HTTP request. Returns parsed JSON or None.
+
+    Raises BastionApiError on non-2xx responses (or auth missing).
+    """
+    creds = resolve_credentials()
+    if require_auth and not creds:
+        raise BastionApiError(
+            "Not logged in. Run `bastion login` (or set BASTION_API_KEY).",
+            status=401,
+        )
+    url = f"{_base_url(creds)}{path}"
+    final_headers = {"Content-Type": "application/json"}
+    if headers:
+        final_headers.update(headers)
+    if creds:
+        final_headers["Authorization"] = f"Bearer {creds['api_key']}"
+
+    request_body: Optional[bytes]
+    if body is None:
+        request_body = None
+    elif isinstance(body, (bytes, str)):
+        request_body = body if isinstance(body, bytes) else body.encode("utf-8")
+    else:
+        request_body = json.dumps(body).encode("utf-8")
+
+    with httpx.Client(timeout=timeout) as client:
+        resp = client.request(method, url, headers=final_headers, content=request_body)
+
+    if resp.status_code >= 400:
+        text_body = ""
+        try:
+            text_body = resp.text
+        except Exception:
+            pass
+        raise BastionApiError(
+            f"HTTP {resp.status_code} on {method} {path}: {text_body[:200]}",
+            status=resp.status_code,
+            body=text_body,
+        )
+
+    ct = resp.headers.get("content-type") or ""
+    if "json" not in ct:
+        return None
+    try:
+        return resp.json()
+    except Exception:
+        return None
+
+
+async def bastion_fetch_async(
+    path: str,
+    *,
+    method: str = "GET",
+    body: Any = None,
+    headers: Optional[dict] = None,
+    require_auth: bool = True,
+    timeout: float = 30.0,
+) -> Any:
+    """Async equivalent of bastion_fetch."""
+    creds = resolve_credentials()
+    if require_auth and not creds:
+        raise BastionApiError(
+            "Not logged in. Run `bastion login` (or set BASTION_API_KEY).",
+            status=401,
+        )
+    url = f"{_base_url(creds)}{path}"
+    final_headers = {"Content-Type": "application/json"}
+    if headers:
+        final_headers.update(headers)
+    if creds:
+        final_headers["Authorization"] = f"Bearer {creds['api_key']}"
+
+    request_body: Optional[bytes]
+    if body is None:
+        request_body = None
+    elif isinstance(body, (bytes, str)):
+        request_body = body if isinstance(body, bytes) else body.encode("utf-8")
+    else:
+        request_body = json.dumps(body).encode("utf-8")
+
+    async with httpx.AsyncClient(timeout=timeout) as client:
+        resp = await client.request(method, url, headers=final_headers, content=request_body)
+
+    if resp.status_code >= 400:
+        text_body = ""
+        try:
+            text_body = resp.text
+        except Exception:
+            pass
+        raise BastionApiError(
+            f"HTTP {resp.status_code} on {method} {path}: {text_body[:200]}",
+            status=resp.status_code,
+            body=text_body,
+        )
+
+    ct = resp.headers.get("content-type") or ""
+    if "json" not in ct:
+        return None
+    try:
+        return resp.json()
+    except Exception:
+        return None

bastion_red-0.4.11/src/bastion/auth/credentials.py

@@ -0,0 +1,66 @@
+"""Credentials store at ~/.bastion/credentials.json.
+
+Resolution order:
+    1. BASTION_API_KEY env var (CI path) - bypasses the file entirely
+    2. ~/.bastion/credentials.json (interactive `bastion login`)
+
+File mode is 0600. Anyone calling resolve_credentials() gets either a
+dict {api_key, source, server_url, ...} or None if neither source is set.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Optional
+
+CREDENTIALS_DIR = Path.home() / ".bastion"
+CREDENTIALS_PATH = CREDENTIALS_DIR / "credentials.json"
+DEFAULT_SERVER_URL = "https://bastion-runner.pistonsolutions.ai"
+
+
+def resolve_credentials() -> Optional[dict]:
+    env_key = os.environ.get("BASTION_API_KEY")
+    if env_key and env_key.strip():
+        return {
+            "api_key": env_key.strip(),
+            "source": "env",
+            "server_url": os.environ.get("BASTION_SERVER_URL", DEFAULT_SERVER_URL),
+        }
+    if not CREDENTIALS_PATH.exists():
+        return None
+    try:
+        data = json.loads(CREDENTIALS_PATH.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not data or not data.get("api_key"):
+        return None
+    return {**data, "source": "file"}
+
+
+def save_credentials(creds: dict) -> None:
+    CREDENTIALS_DIR.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(CREDENTIALS_DIR, 0o700)
+    except OSError:
+        pass
+    payload = {
+        "api_key": creds["api_key"],
+        "user": creds.get("user"),
+        "org_id": creds.get("org_id"),
+        "issued_at": creds.get("issued_at", int(time.time() * 1000)),
+        "server_url": creds.get("server_url", DEFAULT_SERVER_URL),
+    }
+    CREDENTIALS_PATH.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    try:
+        os.chmod(CREDENTIALS_PATH, 0o600)
+    except OSError:
+        pass
+
+
+def clear_credentials() -> bool:
+    if CREDENTIALS_PATH.exists():
+        CREDENTIALS_PATH.unlink()
+        return True
+    return False