feat: initial Python SDK enterprise example with FastAPI, pytest, and agent identity

Author: bordumb

.auths/allowed_signers

@@ -0,0 +1,5 @@
+# Auths allowed signers file
+# Format: <email> ssh-ed25519 <public-key>
+
+alice@example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleKeyAliceReplaceMeWithRealKey000000000
+bob@example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleKeyBobReplaceMeWithARealKey00000000000

.github/workflows/verify-commits.yml

@@ -0,0 +1,24 @@
+name: Verify Commits
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: auths-dev/auths-verify-github-action@v1
+        with:
+          allowed-signers-path: .auths/allowed_signers
+          fail-on-unsigned: true
+          post-pr-comment: 'true'
+          github-token: ${{ secrets.GITHUB_TOKEN }}

Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.12-slim AS builder
+
+WORKDIR /app
+COPY pyproject.toml .
+RUN pip install --no-cache-dir --target=/deps .
+
+FROM python:3.12-slim
+
+WORKDIR /app
+COPY --from=builder /deps /usr/local/lib/python3.12/site-packages
+COPY app/ app/
+
+RUN useradd --create-home appuser
+USER appuser
+
+EXPOSE 8000
+
+CMD ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

LICENSE

@@ -0,0 +1,85 @@
+# Python SDK Enterprise Integration
+
+This example demonstrates how to integrate [Auths](https://github.com/auths-dev/auths) verification into a Python web service using FastAPI. It includes commit and artifact verification endpoints, agent identity workflows, and a pytest test suite.
+
+## Quick Start
+
+```bash
+# 1. Install dependencies
+pip install -e ".[dev]"
+
+# 2. Run the verification service
+uvicorn app.main:app --reload
+
+# 3. Test a verification request
+curl -X POST http://localhost:8000/api/v1/verify-commit \
+  -H "Content-Type: application/json" \
+  -d '{"repo_path": ".", "commit_range": "HEAD~1..HEAD"}'
+```
+
+## What's Included
+
+| Path | Purpose |
+|------|---------|
+| `app/main.py` | FastAPI application with versioned API |
+| `app/routes/verify.py` | `POST /api/v1/verify-commit` and `POST /api/v1/verify-artifact` |
+| `app/routes/health.py` | `GET /health` with SDK version info |
+| `app/services/commit_verifier.py` | Wrapper around `auths.git.verify_commit_range()` |
+| `app/services/artifact_verifier.py` | Wrapper around Auths artifact verification |
+| `app/models.py` | Pydantic request/response models |
+| `agent/deploy_agent.py` | CI agent: sign artifacts during deployment |
+| `agent/audit_agent.py` | Audit agent: verify all commits in repo history |
+| `tests/` | pytest suite with mock fixtures |
+
+## Architecture
+
+```mermaid
+graph LR
+    A[Client] -->|POST /api/v1/verify-commit| B[FastAPI App]
+    A -->|POST /api/v1/verify-artifact| B
+    B --> C[CommitVerifier]
+    B --> D[ArtifactVerifier]
+    C -->|auths.git.verify_commit_range| E[Auths SDK]
+    D -->|auths.Auths.verify| E
+    E --> F[allowed_signers / identity bundles]
+```
+
+## Prerequisites
+
+- Python 3.11+
+- [Auths CLI](https://github.com/auths-dev/auths) (`brew install auths-dev/auths-cli/auths`)
+- Docker (optional, for containerized deployment)
+
+## API Documentation
+
+Start the server and visit `http://localhost:8000/docs` for interactive Swagger documentation.
+
+### Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/api/v1/verify-commit` | Verify commit signatures in a git repository |
+| `POST` | `/api/v1/verify-artifact` | Verify an artifact signature |
+| `GET` | `/health` | Service health check |
+
+## Running Tests
+
+```bash
+pytest -v
+```
+
+## Docker
+
+```bash
+docker compose up --build
+# Service available at http://localhost:8000
+```
+
+## Agent Identity
+
+The `agent/` directory demonstrates how to use Auths agent identities in CI/CD pipelines:
+
+- `deploy_agent.py` — Sign artifacts during deployment using an agent identity
+- `audit_agent.py` — Batch-verify all commits in a repository
+
+See the [Auths Agent Documentation](https://github.com/auths-dev/auths/blob/main/docs/guides/identity/agent-identity.md) for more details.