prodkit 0.1.0__py3-none-any.whl

prodkit/plugins/security/__init__.py

@@ -0,0 +1,78 @@
+"""Security plugin: response security headers, trusted hosts, HTTPS redirect.
+
+Headers follow current OWASP Secure Headers recommendations. CSP is opt-in
+because a wrong default CSP breaks apps; everything else is safe universally.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from starlette.datastructures import MutableHeaders
+from starlette.middleware.httpsredirect import HTTPSRedirectMiddleware
+from starlette.middleware.trustedhost import TrustedHostMiddleware
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from prodkit.contracts.plugin import PRIORITY_SECURITY, Plugin
+from prodkit.core.context import Context
+
+
+class SecurityHeadersMiddleware:
+    """Pure-ASGI middleware (no BaseHTTPMiddleware overhead) that stamps
+    security headers on every response."""
+
+    def __init__(self, app: ASGIApp, headers: dict[str, str]) -> None:
+        self.app = app
+        self.headers = headers
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        async def send_with_headers(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                headers = MutableHeaders(scope=message)
+                for name, value in self.headers.items():
+                    headers.setdefault(name, value)
+            await send(message)
+
+        await self.app(scope, receive, send_with_headers)
+
+
+def build_security_headers(ctx: Context) -> dict[str, str]:
+    cfg = ctx.config.security
+    headers = {
+        "X-Content-Type-Options": "nosniff",
+        "X-Frame-Options": cfg.frame_options,
+        "Referrer-Policy": cfg.referrer_policy,
+        "Permissions-Policy": cfg.permissions_policy,
+        # Kill legacy XSS auditor behavior explicitly (OWASP recommendation).
+        "X-XSS-Protection": "0",
+    }
+    if cfg.hsts:
+        headers["Strict-Transport-Security"] = f"max-age={cfg.hsts_max_age}; includeSubDomains"
+    if cfg.content_security_policy:
+        headers["Content-Security-Policy"] = cfg.content_security_policy
+    return headers
+
+
+class SecurityPlugin(Plugin):
+    name: ClassVar[str] = "security"
+
+    def register_middleware(self, ctx: Context) -> None:
+        cfg = ctx.config.security
+        ctx.add_middleware(
+            SecurityHeadersMiddleware,
+            priority=PRIORITY_SECURITY,
+            headers=build_security_headers(ctx),
+        )
+        if cfg.trusted_hosts:
+            # Slightly outside the headers middleware: reject bad hosts early.
+            ctx.add_middleware(
+                TrustedHostMiddleware,
+                priority=PRIORITY_SECURITY - 10,
+                allowed_hosts=cfg.trusted_hosts,
+            )
+        if cfg.https_redirect:
+            ctx.add_middleware(HTTPSRedirectMiddleware, priority=PRIORITY_SECURITY - 20)

prodkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: prodkit
+Version: 0.1.0
+Summary: The production framework for FastAPI. One line. Production ready.
+Project-URL: Homepage, https://github.com/Pushkarpant/PRODKIT
+Project-URL: Documentation, https://github.com/Pushkarpant/PRODKIT#readme
+Project-URL: Repository, https://github.com/Pushkarpant/PRODKIT
+Project-URL: Changelog, https://github.com/Pushkarpant/PRODKIT/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Pushkarpant/PRODKIT/issues
+Author: ProdKit Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fastapi,health-check,logging,middleware,observability,production,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+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 :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: pydantic-settings>=2.1
+Requires-Dist: pydantic>=2.5
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: brotli
+Requires-Dist: brotli-asgi>=1.4; extra == 'brotli'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: import-linter>=2.0; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: tomli>=2.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ProdKit
+
+> **One line. Production ready.**
+
+The production framework for [FastAPI](https://fastapi.tiangolo.com/).
+
+```python
+from fastapi import FastAPI
+from prodkit import Production
+
+app = FastAPI()
+Production(app)
+```
+
+That's it. Your app now has security headers, structured JSON logging with
+request-ID correlation, RFC 9457 error responses, Kubernetes-ready health
+endpoints, and gzip compression — configured to current best practice,
+hardened for production, and pleasant in development.
+
+[![CI](https://github.com/Pushkarpant/PRODKIT/actions/workflows/ci.yml/badge.svg)](https://github.com/Pushkarpant/PRODKIT/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/prodkit)](https://pypi.org/project/prodkit/)
+[![Python](https://img.shields.io/pypi/pyversions/prodkit)](https://pypi.org/project/prodkit/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Why
+
+Every production FastAPI service re-implements the same ~500 lines of glue:
+middleware ordering, security headers, structured logging, health checks,
+error normalization, graceful shutdown. FastAPI deliberately doesn't ship
+this — it's a micro framework. **ProdKit is the batteries.**
+
+And unlike a project template, ProdKit is a library: when best practices
+evolve, `pip install -U prodkit` updates every app you own.
+
+## Installation
+
+[**`pip install prodkit`**](https://pypi.org/project/prodkit/)
+
+```bash
+pip install prodkit
+```
+
+Requires Python 3.10+ and FastAPI 0.110+. The base install depends only on
+FastAPI and Pydantic — nothing else.
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from prodkit import Production
+
+app = FastAPI()
+Production(app)                      # production profile by default
+
+@app.get("/hello")
+def hello():
+    return {"message": "hello"}
+```
+
+```bash
+uvicorn main:app
+```
+
+```text
+$ curl -i localhost:8000/hello
+HTTP/1.1 200 OK
+x-request-id: 26fdc49565614c2a9ef1a3b8d4e0f712
+x-content-type-options: nosniff
+x-frame-options: DENY
+strict-transport-security: max-age=63072000; includeSubDomains
+referrer-policy: strict-origin-when-cross-origin
+...
+```
+
+For local development, flip the profile — pretty console logs, debug error
+details, no HSTS:
+
+```python
+Production(app, environment="development")
+```
+
+## What You Get
+
+| Feature | Details |
+|---|---|
+| 🆔 **Request IDs** | `X-Request-ID` on every response, propagated into every log line. Inbound IDs untrusted by default. |
+| 📋 **Structured logging** | One JSON object per request in production (Datadog/Loki/CloudWatch-ready); pretty console logs in development. |
+| 🛡️ **Security headers** | OWASP-aligned: `nosniff`, `X-Frame-Options`, HSTS, `Referrer-Policy`, `Permissions-Policy`. Your own headers always win. |
+| 🚨 **Error normalization** | [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `problem+json` responses. Unhandled 500s are **opaque to clients** — the traceback goes to logs, correlated by request ID. |
+| ❤️ **Health endpoints** | `/health`, `/live` (liveness) and `/ready` (readiness — aggregates checks from every plugin, 503 until all pass). Kubernetes-native. |
+| 🌐 **CORS** | Explicit origins only; the wildcard-with-credentials footgun is refused at boot. |
+| 📦 **Compression** | Gzip for responses over 500 bytes. |
+| 🔌 **Plugin system** | Every feature above is a plugin. Write your own with 6 optional hooks. |
+
+## Configuration
+
+Everything is configurable through four layers (highest wins):
+
+```
+Python args  >  environment variables  >  prodkit.toml  >  profile defaults
+```
+
+**Python:**
+
+```python
+Production(
+    app,
+    environment="production",
+    cors={"origins": ["https://app.example.com"]},   # dict = configure & enable
+    compression=False,                                # bool = toggle
+    security={"trusted_hosts": ["api.example.com"]},
+)
+```
+
+**Environment variables** (`__` descends into sections):
+
+```bash
+PRODKIT_ENVIRONMENT=production
+PRODKIT_LOGGING__LEVEL=WARNING
+PRODKIT_SECURITY__TRUSTED_HOSTS=api.example.com,admin.example.com
+```
+
+**`prodkit.toml`:**
+
+```toml
+[prodkit]
+environment = "production"
+
+[logging]
+level = "INFO"
+
+[cors]
+enabled = true
+origins = ["https://app.example.com"]
+```
+
+### Fail-fast, refuse-unsafe
+
+Misconfiguration fails **at startup with a named key**, never silently:
+
+```text
+ProdKitConfigError: Invalid ProdKit configuration:
+  - logging.levle: Extra inputs are not permitted
+```
+
+And configurations that would weaken a production deployment are refused,
+not warned about:
+
+- `debug=True` in production
+- error responses that would leak tracebacks in production
+- CORS `origins=["*"]` combined with `allow_credentials=True`
+
+## Writing a Plugin
+
+```python
+from prodkit import Check, Plugin, Production
+
+class DatabasePlugin(Plugin):
+    name = "database"
+
+    async def startup(self, ctx):
+        self.pool = await create_pool(...)
+        ctx.registry.provide("db", self.pool)
+
+    async def shutdown(self, ctx):
+        await self.pool.close()
+
+    def checks(self, ctx):
+        return [Check(name="database", passed=self.pool.is_alive())]
+
+Production(app, plugins=[DatabasePlugin()])
+```
+
+Your check now shows up in `/ready` automatically. Plugins can declare
+`requires = ("other-plugin",)` and the kernel activates them in dependency
+order — cycles and missing dependencies fail at boot.
+
+Middleware registered by plugins carries an explicit integer priority, so
+the middleware onion is always correctly ordered no matter what order
+plugins load in (request-id outermost, compression innermost).
+
+## Plays Nice With Your App
+
+- **Same app object.** Routes, dependencies, and existing middleware keep
+  working. Remove `Production(app)` and you have a plain FastAPI app again.
+- **Your lifespan survives.** ProdKit *composes* with an existing `lifespan`:
+  plugin startup → your lifespan → plugin shutdown (LIFO).
+- **Your headers win.** Security headers use set-if-absent semantics.
+- **Every feature can be turned off.** `Production(app, security=False, ...)`
+
+## Project Status
+
+**v0.1.0 — alpha.** Core kernel and seven built-in plugins, 60 tests, 98%
+coverage, strict mypy, CI across Python 3.10–3.13.
+
+Roadmap: `prodkit doctor` CLI with a production-readiness score (v0.2),
+Prometheus metrics + Redis backends (v0.3), Dockerfile/nginx/CI generators
+(v0.4), public plugin SDK (v0.5), auth helpers (v0.6), stable API (v1.0).
+Full details in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Contributing
+
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
+Security reports: see [SECURITY.md](SECURITY.md) (never open a public issue).
+
+```bash
+git clone https://github.com/Pushkarpant/PRODKIT
+cd PRODKIT
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+*FastAPI builds APIs. ProdKit makes them production-ready.*

prodkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+prodkit/__init__.py,sha256=cU6DON8Gq38mV0vGsqOOfNVzGisyPjoFMsS4AFSisYI,1286
+prodkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+prodkit/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+prodkit/contracts/plugin.py,sha256=DZntTf1fq97nuWTUXEbSHaxgjrT_JFOvQmADryBbcEo,1713
+prodkit/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+prodkit/core/config.py,sha256=AVNTbSZlSyjevGvEZBa4Bl7RJx_vwVVyZTkzVOvlwwg,8491
+prodkit/core/context.py,sha256=8pQHY2XpbQAOpxz3mfYmWkq2mCDa6Nmka2SkthPG09s,1644
+prodkit/core/event_bus.py,sha256=SptknC8po7wP9NYK5zRqBbWJe0W8BmSt6KNV7UKxih4,1485
+prodkit/core/exceptions.py,sha256=AdujJIe5YjEE-C5p9mYQIEH5x6bxYe2vZf0Ac0l5bqA,598
+prodkit/core/lifecycle.py,sha256=imHauQNQQechsXsGjE1SwliQlEUHBVZQ088XZkJ3zJQ,1716
+prodkit/core/plugin_manager.py,sha256=Hm3MWDGWxuJiBU_oyuYhD1donUytR-3OJjc6FqktwG4,2099
+prodkit/core/production.py,sha256=12BnsGqs6PD9NG6DGJ5HNPNpiXNr0V-smRZuFxdQeLM,4316
+prodkit/core/registry.py,sha256=hxv6gpS659nlwzaFdelXbZCVkBV-kaGb_eLa-Hlr5Mg,1206
+prodkit/plugins/__init__.py,sha256=ucOkndUtRS0KZ-mJQ9erjI_DCADZYpe-k4Pb5F0N9j4,1685
+prodkit/plugins/compression/__init__.py,sha256=ikhnES9z7TdZuF6KmFsmlT2p5S8TCZUJ3H8053QTb-g,654
+prodkit/plugins/cors/__init__.py,sha256=lB1NjtDdCgZfQM9WfbuBiDCgDE5JA-p0xTnhxMJU6YY,1234
+prodkit/plugins/errors/__init__.py,sha256=RtiXpBw1T5Gx7s-zg78OPHsYiE8kjAkrOf4wcT_I0ms,3936
+prodkit/plugins/health/__init__.py,sha256=p6nOQRArHmPF3QSLqxFkyazH9wjgMh92HkOpI6dTvQM,2695
+prodkit/plugins/logging/__init__.py,sha256=9MjwvvICQMZSBRtpGnVIwEGQt8MKqGr5tvQyVWHI_kE,4080
+prodkit/plugins/request_id/__init__.py,sha256=5hLVjlKJJQVz4xV1CJL0c589tx5BfIHxNJG47YfobJA,2140
+prodkit/plugins/security/__init__.py,sha256=KKTA3Gx9ELOhjBTjRvJUOKVkU1mgo1pFa_clSLgQabg,2903
+prodkit-0.1.0.dist-info/METADATA,sha256=VyBQ5SW1MxJdRQPUqam1UqQybh7CfogceoAOhlFSgqU,8698
+prodkit-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+prodkit-0.1.0.dist-info/licenses/LICENSE,sha256=Qvw6r3jRq2Oobj1LnjqC_3V7T46qCLcE69JXpxPKVt4,1068
+prodkit-0.1.0.dist-info/RECORD,,

prodkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

prodkit-0.1.0.dist-info/licenses/LICENSE

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