sovereign-fastapi 1.0.0__py3-none-any.whl

sovereign_fastapi/__init__.py

@@ -0,0 +1,3 @@
+from .middleware import SovereignMiddleware
+
+__all__ = ["SovereignMiddleware"]

sovereign_fastapi/middleware.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+# stdlib
+import json
+import logging
+from typing import Any, Callable, Awaitable, Optional
+
+# framework
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+from starlette.types import ASGIApp
+
+# local
+from sovereign_core.gateway import SovereignGateway
+
+logger = logging.getLogger("sovereign_fastapi")
+
+
+class SovereignMiddleware(BaseHTTPMiddleware):
+    """Drop-in Starlette/FastAPI ASGI middleware that wraps the Sovereign sieve-and-sign
+    pipeline around every inbound JSON request.
+
+    On each request that carries a JSON body the middleware:
+
+    1. Extracts the target text (either the value of ``payload_field`` or the
+       entire serialised body when no field is specified).
+    2. Calls :meth:`~sovereign_core.gateway.SovereignGateway.sieve_and_sign`
+       to strip Prose Tax filler, normalise whitespace, and produce a signed
+       :class:`~sovereign_core.crypto.ForensicReceipt`.
+    3. Overwrites ``request._body`` with the optimised payload so that every
+       downstream route handler transparently receives the cleaned text without
+       any code changes on its side.
+    4. Stores the sealed receipt at ``request.state.sovereign_receipt`` for
+       in-route auditability.
+    5. Injects two headers into the outbound response:
+       - ``X-Sovereign-Receipt-Signature`` — the base64-encoded Ed25519 signature.
+       - ``X-Sovereign-Tokens-Saved`` — the cumulative FinOps savings counter.
+
+    The underlying :meth:`sieve_and_sign` macro captures its
+    :class:`~sovereign_core.gateway.OptimizationReceipt` in coroutine-local
+    scope, so concurrent requests sharing the same middleware instance never
+    bleed per-request metrics into each other's receipts.
+
+    Args:
+        app: The downstream ASGI application to wrap.
+        signing_key: Path to the Ed25519 private key PEM file.  Forwarded
+            directly to :class:`~sovereign_core.gateway.SovereignGateway`.
+            Defaults to ``.keys/sovereign_identity.pem``.
+        strict_mode: When ``True``, any exception raised during body
+            interception (JSON decode error, missing field, key
+            initialisation failure) causes the middleware to abort and
+            return an HTTP 422 Unprocessable Entity response instead of
+            falling through to the downstream handler.  Defaults to
+            ``False``.
+        payload_field: Optional key name to extract from the JSON body as
+            the text to sieve.  When ``None``, the entire body is
+            serialised with :func:`json.dumps` and treated as the input
+            string.  Defaults to ``None``.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        signing_key: str = ".keys/sovereign_identity.pem",
+        strict_mode: bool = False,
+        payload_field: Optional[str] = None,
+    ) -> None:
+        super().__init__(app)
+        self.gateway = SovereignGateway(signing_key=signing_key)
+        self.strict_mode = strict_mode
+        self.payload_field = payload_field
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: Callable[[Request], Awaitable[Response]],
+    ) -> Response:
+        content_type = request.headers.get("content-type", "")
+        receipt: Any = None
+
+        if "application/json" in content_type:
+            # Buffer the body.  _CachedRequest.wrapped_receive (Starlette's
+            # internal mechanism for replaying the body to downstream handlers)
+            # returns self._body verbatim when it is set.  Overwriting _body
+            # after this call is therefore the correct way to transparently
+            # inject a modified payload for every consumer downstream.
+            body_bytes = await request.body()
+            new_body = body_bytes  # default: pass through unchanged on error
+
+            try:
+                body_json = json.loads(body_bytes)
+
+                if self.payload_field is not None:
+                    target_text = str(body_json[self.payload_field])
+                else:
+                    target_text = json.dumps(body_json, ensure_ascii=False)
+
+                result = await self.gateway.sieve_and_sign(target_text)
+                receipt = result.receipt
+                request.state.sovereign_receipt = receipt
+
+                if self.payload_field is not None:
+                    body_json[self.payload_field] = result.content
+                    new_body = json.dumps(body_json, ensure_ascii=False).encode("utf-8")
+                else:
+                    new_body = result.content.encode("utf-8")
+
+            except Exception as exc:
+                if self.strict_mode:
+                    logger.critical(
+                        "Sovereign boundary processing failed under strict enforcement. "
+                        "Aborting request.",
+                        exc_info=True,
+                    )
+                    return JSONResponse(
+                        {"detail": f"Sovereign middleware validation error: {exc}"},
+                        status_code=422,
+                    )
+                logger.error(
+                    "Sovereign boundary processing failed. "
+                    "Bypassing defensively to ensure system availability.",
+                    exc_info=True,
+                )
+
+            # Overwrite the _CachedRequest body cache.  Every downstream
+            # receive() call issued by Starlette's routing layer will replay
+            # this value instead of the original stream.
+            request._body = new_body  # type: ignore[attr-defined]
+
+            # Realign Content-Length with the (possibly sieved) body so that
+            # downstream ASGI handlers, routers, and reverse proxies never
+            # encounter a stale-length mismatch against the overwritten body
+            # bytes or a hanging read timeout waiting for bytes that no longer
+            # exist.
+            new_content_length = str(len(new_body)).encode("utf-8")
+            scope_headers = request.scope["headers"]
+            patched = [
+                (n, new_content_length if n == b"content-length" else v)
+                for n, v in scope_headers
+            ]
+            if not any(n == b"content-length" for n, _ in scope_headers):
+                patched.append((b"content-length", new_content_length))
+            request.scope["headers"] = patched
+
+        response = await call_next(request)
+
+        if receipt is not None:
+            response.headers["X-Sovereign-Receipt-Signature"] = receipt["signature"]
+            tokens_saved = (
+                receipt["metadata"]
+                .get("prose_tax_summary", {})
+                .get("total_tokens_saved", 0)
+            )
+            response.headers["X-Sovereign-Tokens-Saved"] = str(tokens_saved)
+
+        return response

sovereign_fastapi-1.0.0.dist-info/METADATA

@@ -0,0 +1,406 @@
+Metadata-Version: 2.4
+Name: sovereign-fastapi
+Version: 1.0.0
+Summary: FastAPI/Starlette ASGI middleware for the Sovereign Systems SDK
+Author-email: kenwalger <kenalger@comcast.net>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kenwalger/sovereign-sdk
+Project-URL: Repository, https://github.com/kenwalger/sovereign-sdk
+Project-URL: Changelog, https://github.com/kenwalger/sovereign-sdk/blob/main/CHANGELOG.md
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: sovereign-core<2.0.0,>=1.0.0
+Requires-Dist: starlette<1.0.0,>=0.35.0
+
+# Sovereign Systems SDK
+
+**High-Integrity Cryptographic Provenance and Inbound Protection Boundaries for Agentic Workflows.**
+
+Sovereign Systems is a local-first AI WAF and compliance gate. It intercepts every inbound payload before it reaches a model or agentic loop, strips high-entropy boilerplate, and seals the result with an Ed25519-signed `ForensicReceipt` that gives enterprise auditors mathematical proof of un-tampered boundary transformation — all running on local silicon with no external service dependency.
+
+Every boundary crossing produces a non-repudiable chain of custody: the receipt binds the sieved payload hash and the full transformation accounting inside a single cryptographic envelope. No post-hoc mutation of the output or its metrics can go undetected.
+
+To learn more about the philosophy and reasoning behind this project, see [PHILOSOPHY.md](PHILOSOPHY.md).
+
+---
+
+## Why an AI WAF?
+
+Modern agentic pipelines ingest user intent through prompt text. That text is routinely bloated with conversational filler — greetings, hedging adverbs, redundant preambles — that inflates token budgets and introduces non-deterministic reasoning noise without contributing semantic content. At the same time, enterprises operating LLM workloads need the same compliance guarantees they expect from a network WAF: proof that payloads were inspected, proof that the inspection was faithful, and an append-only audit log that is tamper-evident after the fact.
+
+Sovereign Systems provides both:
+
+- **Inbound boundary enforcement** — every payload is sieved before a model or tool sees it.
+- **Cryptographic chain of custody** — every sieved payload is sealed with a node-local Ed25519 private key into a `ForensicReceipt` that persists forever.
+- **Non-repudiation** — the receipt covers the output hash and the transformation accounting under the same signature, so neither the result nor the metrics can be altered without breaking verification.
+- **Local-only execution** — no telemetry leaves the host; key material never leaves the node.
+
+---
+
+## Workspace Topography
+
+This repository is managed as an integrated `uv` workspace separating the cryptographic data tier from the execution runtime:
+
+```text
+.
+├── packages/
+│   ├── sovereign-core/       # Pure data tier (zero high-compute dependencies)
+│   │   └── src/sovereign_core/
+│   │       ├── crypto.py     # Ed25519 key management & ForensicReceipt minting
+│   │       └── gateway.py    # Prose Tax sieve & SovereignGateway high-level API
+│   │
+│   ├── sovereign-runtime/    # Compute/Execution tier (tool & model isolation)
+│   │   └── src/sovereign_runtime/
+│   │       ├── router.py     # Intent-based pre-flight namespace exposure
+│   │       └── __main__.py   # Execution runtime entry point
+│   │
+│   └── sovereign-fastapi/    # FastAPI/Starlette ASGI middleware adapter
+│       └── src/sovereign_fastapi/
+│           └── middleware.py # SovereignMiddleware — sieve-and-sign request interceptor
+│
+├── pyproject.toml            # Monorepo configuration & workspace links
+└── uv.lock                   # Deterministic dependency lockfile
+```
+
+---
+
+## The ForensicReceipt: Sealed Transformation Accounting
+
+Every boundary crossing produces a `ForensicReceipt`. Understanding its structure explains exactly what an enterprise auditor can prove from the output alone.
+
+### What is sealed
+
+The Ed25519 signature inside every receipt covers a single canonical manifest:
+
+```json
+{
+  "metadata": { ... },
+  "payload_hash": "<sha256-of-sieved-content>",
+  "timestamp": "<utc-iso8601>"
+}
+```
+
+`payload_hash` is the SHA-256 digest of the exact sieved string delivered to the model or tool. When the Prose Tax sieve is active, `metadata` always contains a `prose_tax_summary` sub-object:
+
+```json
+"prose_tax_summary": {
+  "raw_token_count": 12,
+  "optimized_token_count": 4,
+  "tokens_eliminated": 8,
+  "tax_savings_percentage": 66.6667,
+  "total_tokens_saved": 8
+}
+```
+
+Because `metadata` is bound inside the signed manifest, these token counts are just as tamper-evident as `payload_hash` itself. An auditor who holds only the node's public key can independently verify:
+
+1. **Output integrity** — the sieved content hasn't been altered after signing (`payload_hash`).
+2. **Transformation accounting** — the before/after token delta recorded at signing time hasn't been fabricated (`prose_tax_summary` is sealed under the same signature).
+3. **Identity provenance** — the receipt was minted by the expected node, not a rogue keypair (`public_key` key-pin assertion).
+
+Together these three checks give mathematical proof that the boundary transformation was faithful and un-tampered — equivalent to a signed audit log with built-in integrity verification.
+
+### Verification workflow
+
+```python
+import asyncio
+import json
+from sovereign_core.gateway import SovereignGateway
+from sovereign_core.crypto import SovereignKeyManager
+
+async def main():
+    gateway = SovereignGateway(signing_key=".keys/sovereign_identity.pem")
+    result = await gateway.sieve_and_sign("Hi! Please just help me now.")
+
+    # result.content == "help me now"
+    # result.receipt["metadata"]["prose_tax_summary"]["tokens_eliminated"] == 4
+
+    # Verify later — requires only the public key and the original sieved payload
+    is_valid = SovereignKeyManager.verify_receipt(
+        result.receipt,
+        {"content": result.content},
+        expected_public_key=gateway.export_public_key(),
+    )
+    assert is_valid  # fails if any field was mutated after signing
+
+asyncio.run(main())
+```
+
+---
+
+## Primary Developer Interface: `SovereignGateway`
+
+`SovereignGateway` is the single entry point for application code. It wraps the full sieve-and-sign pipeline behind a clean four-method API.
+
+### One-shot macro (recommended)
+
+`sieve_and_sign()` strips Prose Tax boilerplate, fuses the transformation telemetry into the receipt metadata, and seals everything in a single awaitable call:
+
+```python
+import asyncio
+from sovereign_core.gateway import SovereignGateway
+
+async def main():
+    gateway = SovereignGateway(signing_key=".keys/sovereign_identity.pem")
+    result = await gateway.sieve_and_sign("Hi! Please just help me now.")
+
+    # result  — SovereignBoundaryResponse (Pydantic model, fully typed)
+    # result.content  — purified string, Prose Tax stripped ("help me now")
+    # result.receipt  — ForensicReceipt with prose_tax_summary sealed inside
+
+    print(result.content)
+    print(result.receipt["payload_hash"])
+
+asyncio.run(main())
+```
+
+Inside a FastAPI route the gateway instance lives on the application object; the route itself is already async:
+
+```python
+from sovereign_core.gateway import SovereignGateway
+
+gateway = SovereignGateway(signing_key=".keys/sovereign_identity.pem")
+
+@app.post("/api/v1/ingest")
+async def handle_agent_input(raw_payload: dict):
+    result = await gateway.sieve_and_sign(raw_payload["text"])
+
+    await reasoning_ledger.append(
+        payload=result.content,
+        receipt=result.receipt,
+    )
+    return {
+        "status": "sovereign_verified",
+        "receipt_id": result.receipt["payload_hash"],
+    }
+```
+
+### Granular two-step workflow
+
+When the clean context is needed before signing (e.g. for intermediate validation or logging):
+
+```python
+import asyncio
+from sovereign_core.gateway import SovereignGateway
+
+async def main():
+    gateway = SovereignGateway(signing_key=".keys/sovereign_identity.pem")
+
+    # 1. Strip Prose Tax — remove boilerplate, normalize whitespace
+    clean_context = await gateway.sieve("Hi! Please just help me now.")
+
+    # 2. Cryptographically seal — transformation telemetry fused into metadata
+    receipt = gateway.sign(clean_context)
+
+    print(clean_context)            # "help me now"
+    print(receipt["payload_hash"])  # SHA-256 of {"content": "help me now"}
+
+asyncio.run(main())
+```
+
+### Independent receipt verification
+
+Receipts produced by either workflow can be verified at any time using only the public key:
+
+```python
+from sovereign_core.crypto import SovereignKeyManager
+
+is_valid = SovereignKeyManager.verify_receipt(
+    receipt,
+    {"content": clean_context},
+    expected_public_key=gateway.export_public_key(),
+)
+```
+
+---
+
+## ASGI Middleware for FastAPI / Starlette
+
+`SovereignMiddleware` applies the sieve-and-sign boundary to every inbound JSON request transparently, without changes to route handlers:
+
+```python
+from fastapi import FastAPI
+from sovereign_fastapi.middleware import SovereignMiddleware
+
+app = FastAPI()
+app.add_middleware(
+    SovereignMiddleware,
+    signing_key=".keys/sovereign_identity.pem",
+    payload_field="text",   # JSON key to sieve; omit to sieve the whole body
+    strict_mode=False,      # True → return HTTP 422 on any interception error
+)
+```
+
+The middleware:
+1. Extracts the target field from the JSON body.
+2. Calls `sieve_and_sign()` on the gateway.
+3. Overwrites `request._body` so every downstream route handler sees the sieved payload.
+4. Caches the sealed receipt at `request.state.sovereign_receipt`.
+5. Injects `X-Sovereign-Receipt-Signature` and `X-Sovereign-Tokens-Saved` on the outbound response.
+
+---
+
+## Prose Tax Optimization
+
+> **This feature is optional.** The cryptographic boundary and ForensicReceipt are produced whether or not any text is eliminated. Prose Tax optimization runs inside the audit envelope — every token count and savings metric is sealed alongside the output hash.
+
+The sieve removes conversational boilerplate that inflates token budgets without contributing semantic content:
+
+| Category | Examples stripped |
+|---|---|
+| Greeting tokens | `hi`, `hello`, `hey`, `greetings` |
+| Hedging adverbs | `just`, `simply`, `actually`, `basically`, `probably` |
+| Affirmation filler | `of course`, `certainly`, `absolutely`, `sure` |
+| Preamble phrases | `I hope this`, `I hope that`, `I hope you` |
+| Politeness tokens | `please`, `kindly` |
+
+All patterns carry negative lookahead guards (e.g. `(?![-\w])`) so technical compound words (`hi-fi`, `just-in-time`, `certainly-not`) pass through unmarred.
+
+---
+
+## Local Development
+
+### Bootstrap
+
+```bash
+uv sync
+```
+
+### Run tests
+
+```bash
+uv run pytest
+```
+
+### Run the sovereign-node runtime
+
+```bash
+uv run sovereign-node
+```
+
+---
+
+## Running the Workspace Examples
+
+### FastAPI Gateway Example
+
+**1. Set your node secret** (required for Ed25519 key generation):
+
+```bash
+export SOVEREIGN_NODE_SECRET=your-local-secret   # Linux / macOS
+$env:SOVEREIGN_NODE_SECRET = "your-local-secret"  # Windows PowerShell
+```
+
+**2. Start the example server:**
+
+```bash
+uv run uvicorn examples.fastapi_gateway.app:app --reload
+```
+
+The server starts on `http://127.0.0.1:8000`. On first boot it generates an Ed25519 keypair at `.keys/example_identity.pem`.
+
+**3. In a second terminal, run the example client:**
+
+```bash
+uv run python examples/fastapi_gateway/client.py
+```
+
+### Verifying a ForensicReceipt (CLI)
+
+Export a receipt and the gateway's public key:
+
+```python
+import asyncio
+import json
+from sovereign_core.gateway import SovereignGateway
+
+async def main():
+    gateway = SovereignGateway()
+    result = await gateway.sieve_and_sign("example payload")
+
+    with open("receipt.json", "w") as f:
+        json.dump(result.receipt, f, indent=2)
+
+    print(gateway.export_public_key())
+
+asyncio.run(main())
+```
+
+Verify the receipt:
+
+```bash
+uv run sovereign-verify \
+    --receipt receipt.json \
+    --public-key <base64-encoded-public-key>
+```
+
+On success:
+
+```
+Verified  ✓  payload_hash: 4fec03e7...
+```
+
+On tampered receipt:
+
+```
+Tampered  ✗  Receipt failed cryptographic verification.
+  payload_hash : 4fec03e7...
+  timestamp    : 2026-05-22T...
+```
+
+---
+
+## Verification & Deep-Dive Diagnostics
+
+### Local Environment Configuration
+
+`SOVEREIGN_NODE_SECRET` can be specified in a `.env` file at the repository root. The node entrypoint loads it automatically via `python-dotenv`:
+
+```bash
+echo 'SOVEREIGN_NODE_SECRET=your-local-secret' > .env
+```
+
+### Standalone Tool Analysis Mode
+
+```bash
+uv run sovereign-node --tool analyze
+```
+
+### Expected Console Output
+
+```
+====================================================
+🟢 Sovereign Node initialization sequence successful.
+====================================================
+🔄 Dispatching single tool execution: 'analyze'...
+⚠️ Standalone mode detected: Context empty. Hydrating baseline diagnostic state...
+
+🔒 Authenticated Forensic Receipt Proof:
+{
+  "timestamp": "2026-05-22T15:00:00.000000+00:00",
+  "payload_hash": "4fec03e7083cca73cfb1152ae1d941b5a5a581fc725a43b3ee7df1d9ce697954",
+  "public_key": "<base64-encoded Ed25519 public key>",
+  "signature": "<base64-encoded Ed25519 signature>",
+  "metadata": {
+    "runtime": "async-sovereign-node",
+    "py_ver": "3.12.x",
+    "execution_success": true
+  }
+}
+```
+
+**Line-by-line interpretation:**
+
+| Output line | What it proves |
+|---|---|
+| `🟢 Sovereign Node initialization sequence successful.` | Ed25519 keypair loaded or generated; `SOVEREIGN_NODE_SECRET` resolved; router and session context initialised. |
+| `⚠️ Standalone mode detected …` | The `analyze` tool detected no upstream context and self-hydrated a baseline telemetry stream — expected behaviour in single-tool invocations. |
+| `"payload_hash": "4fec03e7…"` | SHA-256 digest of the deterministically serialised execution payload. |
+| `"public_key": "<base64>"` | Base64-encoded raw Ed25519 public key; verified by `_audit_receipt` before process exit. |
+| `"signature": "<base64>"` | Ed25519 signature over `{"metadata": …, "payload_hash": …, "timestamp": …}`. Any mutation of these fields after issuance causes `verify_receipt` to return `False`. |
+| `"execution_success": true` | The tool completed without raising an exception; the receipt is audit-clean. |

sovereign_fastapi-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+sovereign_fastapi/__init__.py,sha256=I7y7C9IQsUMRAV5HxEqdKTaXoyFBOVQIcKr0YqBjcIk,79
+sovereign_fastapi/middleware.py,sha256=sXaYnMFFqO9tpLmR_okj7zYvnZyC0md3NZ-F0iXMI3E,6890
+sovereign_fastapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sovereign_fastapi-1.0.0.dist-info/METADATA,sha256=vPpm9Y5MOzWCiLeLMa8WFb74z_nr8tPvdi-YPwmYje4,14702
+sovereign_fastapi-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sovereign_fastapi-1.0.0.dist-info/top_level.txt,sha256=8vPSE0N4U5jzc0YTepL1lDJgABbLePpqImOQyDvRg2c,18
+sovereign_fastapi-1.0.0.dist-info/RECORD,,

sovereign_fastapi-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sovereign_fastapi-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sovereign_fastapi