sirr 0.1.0__tar.gz

sirr-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest --cov=sirr --cov-report=term-missing
+
+  publish:
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      id-token: write
+    environment: release
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

sirr-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+*.so
+.venv/
+venv/
+env/

sirr-0.1.0/CLAUDE.md

@@ -0,0 +1,84 @@
+# sirr Python Client — Claude Development Guide
+
+## Purpose
+
+Python HTTP client for the Sirr API. Published to PyPI as `sirr`.
+Supports both sync and async usage.
+
+## Architecture
+
+```
+src/sirr/
+├── __init__.py          # Re-exports: SirrClient, AsyncSirrClient, SecretMeta, SirrError
+├── _exceptions.py       # SirrError(status, message)
+├── _models.py           # SecretMeta frozen dataclass with from_dict()
+├── _transport.py        # Shared: build_headers, normalize_server, handle_response
+├── _client.py           # SirrClient (sync, httpx.Client)
+├── _async_client.py     # AsyncSirrClient (async, httpx.AsyncClient)
+└── py.typed             # PEP 561 marker
+```
+
+**DRY strategy**: `_transport.py` handles headers, URL normalization, and response parsing.
+Both clients call into it. No base class — the duplication across 6 methods is minimal.
+
+## API Surface
+
+```python
+class SirrClient:
+    def __init__(self, server: str, token: str): ...
+
+    # Sync
+    def push(self, key: str, value: str, *, ttl: int | None = None, reads: int | None = None) -> None
+    def get(self, key: str) -> str | None          # None if burned/expired
+    def delete(self, key: str) -> None
+    def list(self) -> list[SecretMeta]
+    def pull_all(self) -> dict[str, str]
+    def prune(self) -> int
+    def env(self) -> ContextManager                # injects into os.environ
+
+class AsyncSirrClient:
+    # Same surface but all methods are async
+    # pull_all() uses asyncio.gather for concurrent fetches
+    # env() is an @asynccontextmanager
+```
+
+## Stack
+
+- Python 3.10+
+- `httpx` for HTTP (supports both sync and async)
+- `pytest` + `pytest-asyncio` + `respx` for tests
+- `ruff` for linting and formatting
+- `hatchling` build backend
+- Published via `pyproject.toml` (no setup.py)
+
+## Key Rules
+
+- `get()` returns `None` on 404 — do not raise
+- All other non-2xx responses raise `SirrError`
+- Never log secret values
+- `env()` context manager must restore original env on exit (even on exception)
+- Keys are URL-encoded in paths (`urllib.parse.quote(key, safe='')`)
+
+## Commands
+
+```bash
+# Install (editable + dev deps)
+pip install -e ".[dev]"
+
+# Lint
+ruff check src/ tests/
+ruff format --check src/ tests/
+
+# Test
+pytest --cov=sirr --cov-report=term-missing
+
+# Build
+python -m build
+```
+
+## Pre-Commit Checklist
+
+Before every commit and push, review and update if needed:
+
+1. **README.md** — Does it reflect new methods or behavior?
+2. **CLAUDE.md** — New constraints or API decisions worth recording?

sirr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sirrlock
+
+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.

sirr-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.5
+Name: sirr
+Version: 0.1.0
+Summary: Python client for the Sirr ephemeral secret vault
+Project-URL: Homepage, https://github.com/sirrlock/python
+Project-URL: Repository, https://github.com/sirrlock/python
+Author: sirrlock
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,ephemeral,secrets,vault
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=6; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sirr (Python)
+
+[![CI](https://github.com/sirrlock/python/actions/workflows/ci.yml/badge.svg)](https://github.com/sirrlock/python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/sirr)](https://pypi.org/project/sirr/)
+[![Python](https://img.shields.io/pypi/pyversions/sirr)](https://pypi.org/project/sirr/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Ephemeral secrets for Python AI agents. Credentials that delete themselves.**
+
+`sirr` is the Python client for [Sirr](https://github.com/sirrlock/sirr) — a self-hosted vault where every secret expires by read count, by time, or both. Built for the Python AI ecosystem: LangChain, CrewAI, AutoGen, LlamaIndex, and any framework that needs to hand credentials to agents without leaving them lying around forever.
+
+---
+
+## The Problem It Solves
+
+Python dominates the AI/ML landscape. That means Python is where credentials get handed to agents, embedded in tool calls, interpolated into prompts, and logged by frameworks. Every time an agent reads a database URL or API key, you have limited visibility into what that framework stored, logged, or will use for fine-tuning.
+
+The standard answer — "rotate your secrets after every session" — doesn't scale. You forget. It's tedious. It requires manual IAM work.
+
+Sirr gives you a better primitive: **credentials that enforce their own expiry.** An agent reads it once. The server deletes it. You don't have to remember to clean anything up.
+
+```python
+# Give a CrewAI agent exactly one read of your API key
+sirr.push("OPENAI_KEY", api_key, reads=1, ttl=600)
+
+# Agent calls sirr.get("OPENAI_KEY") → gets the value → record deleted
+# Even if CrewAI logs the value to its trace file, it's already dead on your server
+```
+
+---
+
+## Install
+
+```bash
+pip install sirr
+```
+
+Requires Python 3.10+. Supports sync and async.
+
+---
+
+## Usage
+
+```python
+import os
+from sirr import SirrClient
+
+sirr = SirrClient(
+    server=os.environ.get("SIRR_SERVER", "http://localhost:8080"),
+    token=os.environ["SIRR_TOKEN"],
+)
+
+# Push a one-time secret
+sirr.push("API_KEY", "sk-...", reads=1, ttl=3600)
+
+# Retrieve — None if burned or expired
+value = sirr.get("API_KEY")
+
+# Pull all secrets into a dict
+secrets = sirr.pull_all()
+# → {"API_KEY": "sk-...", "DB_URL": "postgres://..."}
+
+# Inject as environment variables for the duration of a block
+with sirr.env():
+    # os.environ["API_KEY"] is set here
+    run_agent_task()
+    # restored on exit, even on exception
+
+# Delete immediately
+sirr.delete("API_KEY")
+
+# List active secrets (metadata only — no values)
+entries = sirr.list()
+
+# Prune expired secrets
+pruned = sirr.prune()
+```
+
+### Async
+
+```python
+from sirr import AsyncSirrClient
+
+async with AsyncSirrClient(server=..., token=...) as sirr:
+    await sirr.push("API_KEY", "sk-...", reads=1, ttl=3600)
+    value = await sirr.get("API_KEY")
+```
+
+---
+
+## AI Workflows
+
+### LangChain tool with scoped credential
+
+```python
+from langchain.tools import tool
+
+@tool
+def query_production_db(sql: str) -> str:
+    """Run a SQL query against the production database."""
+    conn_str = sirr.get("AGENT_DB")
+    if conn_str is None:
+        raise ValueError("DB credential expired or already used")
+    return run_query(conn_str, sql)
+```
+
+### CrewAI agent with burn-after-use credential
+
+```python
+from crewai import Agent, Task, Crew
+
+# Push before the crew runs — burns after first read
+sirr.push("STRIPE_KEY", stripe_key, reads=1, ttl=600)
+
+analyst = Agent(
+    role="Data Analyst",
+    goal="Fetch and analyze payment data",
+    tools=[stripe_tool],  # tool calls sirr.get("STRIPE_KEY") internally
+)
+
+crew = Crew(agents=[analyst], tasks=[analysis_task])
+crew.kickoff()
+# STRIPE_KEY was read once by the tool — already deleted
+```
+
+### AutoGen multi-agent with isolated credentials
+
+```python
+import autogen
+
+# Each agent gets its own scoped, expiring credential
+sirr.push("AGENT_1_DB", db_url_1, reads=5, ttl=3600)
+sirr.push("AGENT_2_DB", db_url_2, reads=5, ttl=3600)
+
+# Agents run — their credential budgets are enforced server-side
+# No agent can exceed its read limit even if the framework retries
+```
+
+### Inject all secrets into a subprocess
+
+```python
+with sirr.env():
+    # All Sirr secrets set as os.environ
+    subprocess.run(["python", "agent_script.py"])
+# Env restored after block
+```
+
+### pytest fixture for CI secrets
+
+```python
+import pytest
+from sirr import SirrClient
+
+@pytest.fixture(autouse=True)
+def inject_test_secrets():
+    sirr = SirrClient(server=os.environ["SIRR_SERVER"], token=os.environ["SIRR_TOKEN"])
+    with sirr.env():
+        yield
+    # Credentials cleaned from env after each test
+```
+
+---
+
+## Related
+
+| Package | Description |
+|---------|-------------|
+| [sirr](https://github.com/sirrlock/sirr) | Rust monorepo: `sirrd` server + `sirr` CLI |
+| [@sirrlock/mcp](https://github.com/sirrlock/mcp) | MCP server for AI assistants |
+| [@sirrlock/node](https://github.com/sirrlock/node) | Node.js / TypeScript SDK |
+| [Sirr.Client (NuGet)](https://github.com/sirrlock/dotnet) | .NET SDK |
+| [sirr.dev](https://sirr.dev) | Documentation |
+| [sirrlock.com](https://sirrlock.com) | Managed cloud + license keys |

sirr-0.1.0/README.md

@@ -0,0 +1,173 @@
+# sirr (Python)
+
+[![CI](https://github.com/sirrlock/python/actions/workflows/ci.yml/badge.svg)](https://github.com/sirrlock/python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/sirr)](https://pypi.org/project/sirr/)
+[![Python](https://img.shields.io/pypi/pyversions/sirr)](https://pypi.org/project/sirr/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Ephemeral secrets for Python AI agents. Credentials that delete themselves.**
+
+`sirr` is the Python client for [Sirr](https://github.com/sirrlock/sirr) — a self-hosted vault where every secret expires by read count, by time, or both. Built for the Python AI ecosystem: LangChain, CrewAI, AutoGen, LlamaIndex, and any framework that needs to hand credentials to agents without leaving them lying around forever.
+
+---
+
+## The Problem It Solves
+
+Python dominates the AI/ML landscape. That means Python is where credentials get handed to agents, embedded in tool calls, interpolated into prompts, and logged by frameworks. Every time an agent reads a database URL or API key, you have limited visibility into what that framework stored, logged, or will use for fine-tuning.
+
+The standard answer — "rotate your secrets after every session" — doesn't scale. You forget. It's tedious. It requires manual IAM work.
+
+Sirr gives you a better primitive: **credentials that enforce their own expiry.** An agent reads it once. The server deletes it. You don't have to remember to clean anything up.
+
+```python
+# Give a CrewAI agent exactly one read of your API key
+sirr.push("OPENAI_KEY", api_key, reads=1, ttl=600)
+
+# Agent calls sirr.get("OPENAI_KEY") → gets the value → record deleted
+# Even if CrewAI logs the value to its trace file, it's already dead on your server
+```
+
+---
+
+## Install
+
+```bash
+pip install sirr
+```
+
+Requires Python 3.10+. Supports sync and async.
+
+---
+
+## Usage
+
+```python
+import os
+from sirr import SirrClient
+
+sirr = SirrClient(
+    server=os.environ.get("SIRR_SERVER", "http://localhost:8080"),
+    token=os.environ["SIRR_TOKEN"],
+)
+
+# Push a one-time secret
+sirr.push("API_KEY", "sk-...", reads=1, ttl=3600)
+
+# Retrieve — None if burned or expired
+value = sirr.get("API_KEY")
+
+# Pull all secrets into a dict
+secrets = sirr.pull_all()
+# → {"API_KEY": "sk-...", "DB_URL": "postgres://..."}
+
+# Inject as environment variables for the duration of a block
+with sirr.env():
+    # os.environ["API_KEY"] is set here
+    run_agent_task()
+    # restored on exit, even on exception
+
+# Delete immediately
+sirr.delete("API_KEY")
+
+# List active secrets (metadata only — no values)
+entries = sirr.list()
+
+# Prune expired secrets
+pruned = sirr.prune()
+```
+
+### Async
+
+```python
+from sirr import AsyncSirrClient
+
+async with AsyncSirrClient(server=..., token=...) as sirr:
+    await sirr.push("API_KEY", "sk-...", reads=1, ttl=3600)
+    value = await sirr.get("API_KEY")
+```
+
+---
+
+## AI Workflows
+
+### LangChain tool with scoped credential
+
+```python
+from langchain.tools import tool
+
+@tool
+def query_production_db(sql: str) -> str:
+    """Run a SQL query against the production database."""
+    conn_str = sirr.get("AGENT_DB")
+    if conn_str is None:
+        raise ValueError("DB credential expired or already used")
+    return run_query(conn_str, sql)
+```
+
+### CrewAI agent with burn-after-use credential
+
+```python
+from crewai import Agent, Task, Crew
+
+# Push before the crew runs — burns after first read
+sirr.push("STRIPE_KEY", stripe_key, reads=1, ttl=600)
+
+analyst = Agent(
+    role="Data Analyst",
+    goal="Fetch and analyze payment data",
+    tools=[stripe_tool],  # tool calls sirr.get("STRIPE_KEY") internally
+)
+
+crew = Crew(agents=[analyst], tasks=[analysis_task])
+crew.kickoff()
+# STRIPE_KEY was read once by the tool — already deleted
+```
+
+### AutoGen multi-agent with isolated credentials
+
+```python
+import autogen
+
+# Each agent gets its own scoped, expiring credential
+sirr.push("AGENT_1_DB", db_url_1, reads=5, ttl=3600)
+sirr.push("AGENT_2_DB", db_url_2, reads=5, ttl=3600)
+
+# Agents run — their credential budgets are enforced server-side
+# No agent can exceed its read limit even if the framework retries
+```
+
+### Inject all secrets into a subprocess
+
+```python
+with sirr.env():
+    # All Sirr secrets set as os.environ
+    subprocess.run(["python", "agent_script.py"])
+# Env restored after block
+```
+
+### pytest fixture for CI secrets
+
+```python
+import pytest
+from sirr import SirrClient
+
+@pytest.fixture(autouse=True)
+def inject_test_secrets():
+    sirr = SirrClient(server=os.environ["SIRR_SERVER"], token=os.environ["SIRR_TOKEN"])
+    with sirr.env():
+        yield
+    # Credentials cleaned from env after each test
+```
+
+---
+
+## Related
+
+| Package | Description |
+|---------|-------------|
+| [sirr](https://github.com/sirrlock/sirr) | Rust monorepo: `sirrd` server + `sirr` CLI |
+| [@sirrlock/mcp](https://github.com/sirrlock/mcp) | MCP server for AI assistants |
+| [@sirrlock/node](https://github.com/sirrlock/node) | Node.js / TypeScript SDK |
+| [Sirr.Client (NuGet)](https://github.com/sirrlock/dotnet) | .NET SDK |
+| [sirr.dev](https://sirr.dev) | Documentation |
+| [sirrlock.com](https://sirrlock.com) | Managed cloud + license keys |

sirr-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sirr"
+version = "0.1.0"
+description = "Python client for the Sirr ephemeral secret vault"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "sirrlock" }]
+keywords = ["secrets", "vault", "ephemeral", "ai", "agents"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "respx>=0.22",
+    "ruff>=0.9",
+    "pytest-cov>=6",
+    "build",
+]
+
+[project.urls]
+Homepage = "https://github.com/sirrlock/python"
+Repository = "https://github.com/sirrlock/python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sirr"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

sirr-0.1.0/src/sirr/__init__.py

@@ -0,0 +1,25 @@
+"""sirr — Python client for the Sirr ephemeral secret vault."""
+
+from sirr._async_client import AsyncSirrClient
+from sirr._client import SirrClient
+from sirr._exceptions import SirrError
+from sirr._models import (
+    ApiKey,
+    ApiKeyCreateResult,
+    AuditEvent,
+    SecretMeta,
+    Webhook,
+    WebhookCreateResult,
+)
+
+__all__ = [
+    "ApiKey",
+    "ApiKeyCreateResult",
+    "AsyncSirrClient",
+    "AuditEvent",
+    "SecretMeta",
+    "SirrClient",
+    "SirrError",
+    "Webhook",
+    "WebhookCreateResult",
+]