camada 0.2.0__tar.gz

camada-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env

camada-0.2.0/LICENSE

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

camada-0.2.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.5
+Name: camada
+Version: 0.2.0
+Summary: camada SDK for Python: inline enforcement of your snapshot (ordered custom rules, then allow, block, challenge), first-party beacon and proof-of-work challenge, batched event shipping. ASGI and WSGI middleware; Django, Flask and FastAPI integrations.
+Project-URL: Homepage, https://camada.app
+Project-URL: Repository, https://github.com/camada-app/camada-python
+Project-URL: Issues, https://github.com/camada-app/camada-python/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# camada
+
+camada for Python: enforces the tenant snapshot inline (your ordered custom rules, then allow,
+block, challenge), serves a first-party proof-of-work challenge page and beacon, records the
+outcomes your handlers know (`track()`), and ships wire events in batches off the request path.
+One package on PyPI with an ASGI middleware (the first-class tier: it keeps the wire's header
+order), a WSGI middleware, and integrations for FastAPI, Django and Flask — the `sentry-sdk`
+model. Fails open by design: a camada outage or bug never 5xxes your app.
+
+Not yet on PyPI — install it from a sibling checkout: `pip install -e ../camada-python` (or a uv
+path dependency, as [`camada-python-example`](../camada-python-example) does); publishing is one
+decision with the npm packages (SDK-G01). Python 3.10 or newer, no runtime dependencies.
+
+## Quickstart
+
+```python
+# FastAPI / Starlette
+from camada.fastapi import CamadaMiddleware
+app.add_middleware(CamadaMiddleware)   # last, so it runs outermost
+
+# Django — settings.py
+MIDDLEWARE = ["camada.django.CamadaMiddleware", *MIDDLEWARE]   # first
+
+# Flask
+from camada.flask import init_app
+init_app(app)   # wraps app.wsgi_app, so camada answers before routing
+
+# any ASGI 3 or WSGI app
+from camada.asgi import CamadaASGI      # application = CamadaASGI(application)
+from camada.wsgi import CamadaWSGI      # application = CamadaWSGI(application)
+```
+
+Env (printed by camada onboarding / `npm run seed` in dev):
+
+```
+CAMADA_KEY=<ingest_token>.<snap_token>
+CAMADA_INGEST_URL=http://localhost:8787        # dev only; defaults to production ingest
+```
+
+The integrations share one lazy engine built from the environment on the first request. That
+build starts the snapshot poll on a thread and never blocks, so the request that triggered it is
+answered cold: it passes (fail open), and so does anything else that arrives before that first
+poll lands (a few hundred milliseconds against a local analyst; snapshot-size and network bound).
+To enforce from request 1, warm the engine in a startup hook by waiting for the boot poll —
+`snap.refresh()` alone is not it, the boot poll already holds the single-in-flight lock:
+
+```python
+import time
+import camada
+from camada.snapshot.match import MatchInput
+
+engine = camada.get_default()   # builds the engine; the boot poll is already running on its thread
+if engine.snap:                 # None when CAMADA_KEY is unset or CAMADA_DISABLED=1
+    deadline = time.monotonic() + 5
+    while engine.snap.verdict(MatchInput(ip="0.0.0.0")).reason == "cold" and time.monotonic() < deadline:
+        time.sleep(0.01)        # bounded: an unreachable analyst leaves it cold, and the app still fails open
+```
+
+`snap.refresh()` is not the warm-up: the boot poll holds the single-in-flight lock, so a
+synchronous `refresh()` called right after `get_default()` returns at once and the engine is
+still cold.
+
+Without `CAMADA_KEY` the engine is inert (one log line, no requests, no enforcement). An app that
+reads its own config builds the engine itself and hands it in:
+
+```python
+from camada import Camada
+engine = Camada(env={"CAMADA_KEY": MY_KEY, "CAMADA_INGEST_URL": MY_INGEST})
+app.add_middleware(CamadaMiddleware, engine=engine)      # init_app(app, engine=engine) for Flask
+```
+
+## What it does per request
+
+1. Keeps the snapshot fresh. A Python server is a long-lived process, so the default is a daemon
+   poll thread at the cadence your tenant config sets (`poll_seconds`), with ETag/304 and gzip on
+   the wire. `CAMADA_SERVERLESS=1` switches to a per-request staleness check with no thread. Every
+   poll and event batch carries `x-camada-sdk: @camada/python/<version>`, and polls ask for
+   snapshot v5 (`x-camada-snapshot: 5`) — the container that carries your ordered custom rules.
+2. Resolves the client from the socket peer (`REMOTE_ADDR` / `scope["client"]`), combined with
+   `X-Forwarded-For` only under your tenant's trusted-proxy config (or `CAMADA_TRUSTED_PROXY`
+   locally). A forwarded header on its own is never the ip: any caller can set it.
+3. Enforces before anything else, beacon endpoints included: your ordered custom rules first (first
+   match wins; they read ip, path, user-agent and request headers), then allow → block → challenge.
+   A block answers `403 Forbidden` with `x-block-reason`, `x-block-version` and, when a rule
+   decided, `x-block-rule`; its event ships with `blk` (and `rl`). A `warn` rule passes and stamps
+   `wrn`; a `skip` rule passes with nothing stamped. Cold (no snapshot yet) passes: fail open.
+4. Challenge: a `challenge` verdict gets the self-contained proof-of-work page (or 403 JSON for a
+   non-HTML request); `POST /__camada/challenge` verifies the solution, sets `_cch` (bound to the
+   ip, one hour) and 302s back. A request whose ip cannot be resolved is never challenged.
+5. Serves the beacon: `GET /_cam/b.js` (the `@camada/browser` build, vendored) and `POST /_cam/fp`
+   (≤ 32 KB, relayed onto the event batch as a `sig: 1` row with the ip camada resolved). Both
+   fall through to your app when the tenant switched the beacon off.
+6. Runs your app with `x-rid` and the `_sfp` session cookie on its response, and when the response
+   is done ships one redacted event: method, host, path, scrubbed query, status, latency, header
+   names/sizes/order, the auth scheme (never the credential), cookie count (never values). An
+   exception in your app ships as `st: 500` and propagates unchanged.
+
+## Options
+
+`Camada(...)` keyword arguments; everything credential-shaped comes from the environment.
+
+| option | default | meaning |
+|---|---|---|
+| `env` | `os.environ` | where `CAMADA_*` are read from |
+| `transport` | urllib | the HTTP callable that reaches the analyst (tests inject a fake) |
+| `refresh_s` | server-steered | poll cadence; set, it is pinned |
+| `challenge` | `True` | serve the proof-of-work page for challenge verdicts (`CAMADA_CHALLENGE=0` too) |
+| `challenge_path` | `/__camada/challenge` | where the page posts its solution |
+| `snapshot_version` | `5` | 4 drops your custom rules; 3 the allow/challenge sides too |
+| `script_path` / `fp_path` | `/_cam/b.js` / `/_cam/fp` | the beacon endpoints; keep them in one directory |
+
+Env: `CAMADA_KEY` (or `CAMADA_TOKEN` + `CAMADA_SNAPSHOT_TOKEN`), `CAMADA_INGEST_URL`,
+`CAMADA_SNAPSHOT_URL`, `CAMADA_TRUSTED_PROXY` (`none | vercel | hops:N | cidrs:a,b`),
+`CAMADA_SERVERLESS=1`, `CAMADA_CHALLENGE=0`, and the kill switch `CAMADA_DISABLED=1` (checked per
+request; set at boot, no threads start at all).
+
+## The first-party beacon
+
+```python
+from camada.fastapi import script_tag        # camada.django: script_tag(request); camada.flask: script_tag()
+return HTMLResponse(f"<html><head>{script_tag(request)}</head>…")
+```
+
+The tag is `<script src="/_cam/b.js?r=<rid>" async>`, so the beacon joins the page view that
+served it. Move both paths with `script_path` / `fp_path` when `/_cam/` is not yours; the script
+derives the post path from its own URL, so the two must share a directory.
+
+## App-context events
+
+```python
+from camada.fastapi import track             # camada.django: track(request, ...); camada.flask: track(event, user=...)
+track(request, "login_failed", user=email)
+```
+
+The identifier is HMAC-hashed in-process with your ingest token; the raw value never reaches the
+queue. `track()` never raises and is a no-op on a request the middleware did not run for. The
+event name is free-form; the analyst's app-context rules read this vocabulary:
+
+| event | when |
+|---|---|
+| `login_failed` / `login_succeeded` | a login attempt settled; pass `user=` so attempts per account can be counted |
+| `signup` | an account was created |
+| `password_reset` | a reset was requested |
+| `mfa_failed` | a second factor was rejected |
+| `payment_failed` / `payment_succeeded` | a payment authorisation settled |
+| `coupon_failed` | a promo/voucher code was rejected |
+
+A route you gate yourself: `serve_challenge(request)` (Flask: `serve_challenge()`) returns the
+page as a framework response to return from the handler until the browser holds a valid `_cch`,
+then `None`.
+
+## What this tap can see
+
+`sdk-python` is an in-app tap: status, latency, session, the beacon's browser signals and your
+outcomes. Under ASGI the event also carries the wire's header order (`hord`); WSGI's `environ`
+loses it, which is why ASGI is the first-class tier. The analyst knows what this tap can see and
+never scores the absence of header order, ASN, country or a TLS fingerprint against a request;
+ASN and country it resolves itself. Enforcement at this position covers ip, path, user-agent and
+header conditions — ASN, country and TLS entries fail open in-app. `matches` patterns are JS
+regexes read by Python's `re` (named groups, `[^]` and `\cX` are translated, `\d`/`\w`/`\b` stay
+ASCII); a spelling `re` still rejects never matches here, while it does at the edge.
+
+## Deploying it
+
+- Every worker process polls its own snapshot (about 5 MB resident) and flushes its own batches;
+  the tenant's `poll_seconds` keeps the cadence honest across a fleet.
+- Threads do not survive a fork. Under gunicorn `--preload` or uWSGI the SDK notices the fork
+  (`os.register_at_fork`) and restarts its poll and flush threads in each worker.
+- Pending events drain at interpreter exit within half a second. No signal handlers are
+  installed — an app owns its own shutdown — so a worker killed by SIGTERM without one may drop
+  its last batch.
+- Serverless: `CAMADA_SERVERLESS=1`. A cold invocation fails open and catches up on the next one.
+
+## Fail open
+
+Every entry point runs inside the fail-open envelope: a dead ingest drops telemetry (logged at
+most once a minute), a corrupt snapshot keeps the previous one, a bug in the package costs the
+request its join, never its response. `CAMADA_DISABLED=1` bypasses everything.
+
+## Development
+
+```
+uv sync && uv run ruff check && uv run mypy && uv run pytest
+```
+
+The suite reads the golden snapshot fixtures from the `camada-core` sibling checkout and pins the
+vendored beacon to `camada-browser/dist/auto.global.js` (`npm run build` there first, then
+`python scripts/sync_beacon.py` after a beacon release). Both fail by name when the checkout is
+missing rather than skipping.
+
+[`camada-python-example`](../camada-python-example) is the hand-test bench (FastAPI under uvicorn on
+:3002), and `node scripts/e2e-sdk-python.mjs` in `camada/edge-analyst` drives it against a seeded
+local analyst over real HTTP, cold first request included.

camada-0.2.0/README.md

@@ -0,0 +1,193 @@
+# camada
+
+camada for Python: enforces the tenant snapshot inline (your ordered custom rules, then allow,
+block, challenge), serves a first-party proof-of-work challenge page and beacon, records the
+outcomes your handlers know (`track()`), and ships wire events in batches off the request path.
+One package on PyPI with an ASGI middleware (the first-class tier: it keeps the wire's header
+order), a WSGI middleware, and integrations for FastAPI, Django and Flask — the `sentry-sdk`
+model. Fails open by design: a camada outage or bug never 5xxes your app.
+
+Not yet on PyPI — install it from a sibling checkout: `pip install -e ../camada-python` (or a uv
+path dependency, as [`camada-python-example`](../camada-python-example) does); publishing is one
+decision with the npm packages (SDK-G01). Python 3.10 or newer, no runtime dependencies.
+
+## Quickstart
+
+```python
+# FastAPI / Starlette
+from camada.fastapi import CamadaMiddleware
+app.add_middleware(CamadaMiddleware)   # last, so it runs outermost
+
+# Django — settings.py
+MIDDLEWARE = ["camada.django.CamadaMiddleware", *MIDDLEWARE]   # first
+
+# Flask
+from camada.flask import init_app
+init_app(app)   # wraps app.wsgi_app, so camada answers before routing
+
+# any ASGI 3 or WSGI app
+from camada.asgi import CamadaASGI      # application = CamadaASGI(application)
+from camada.wsgi import CamadaWSGI      # application = CamadaWSGI(application)
+```
+
+Env (printed by camada onboarding / `npm run seed` in dev):
+
+```
+CAMADA_KEY=<ingest_token>.<snap_token>
+CAMADA_INGEST_URL=http://localhost:8787        # dev only; defaults to production ingest
+```
+
+The integrations share one lazy engine built from the environment on the first request. That
+build starts the snapshot poll on a thread and never blocks, so the request that triggered it is
+answered cold: it passes (fail open), and so does anything else that arrives before that first
+poll lands (a few hundred milliseconds against a local analyst; snapshot-size and network bound).
+To enforce from request 1, warm the engine in a startup hook by waiting for the boot poll —
+`snap.refresh()` alone is not it, the boot poll already holds the single-in-flight lock:
+
+```python
+import time
+import camada
+from camada.snapshot.match import MatchInput
+
+engine = camada.get_default()   # builds the engine; the boot poll is already running on its thread
+if engine.snap:                 # None when CAMADA_KEY is unset or CAMADA_DISABLED=1
+    deadline = time.monotonic() + 5
+    while engine.snap.verdict(MatchInput(ip="0.0.0.0")).reason == "cold" and time.monotonic() < deadline:
+        time.sleep(0.01)        # bounded: an unreachable analyst leaves it cold, and the app still fails open
+```
+
+`snap.refresh()` is not the warm-up: the boot poll holds the single-in-flight lock, so a
+synchronous `refresh()` called right after `get_default()` returns at once and the engine is
+still cold.
+
+Without `CAMADA_KEY` the engine is inert (one log line, no requests, no enforcement). An app that
+reads its own config builds the engine itself and hands it in:
+
+```python
+from camada import Camada
+engine = Camada(env={"CAMADA_KEY": MY_KEY, "CAMADA_INGEST_URL": MY_INGEST})
+app.add_middleware(CamadaMiddleware, engine=engine)      # init_app(app, engine=engine) for Flask
+```
+
+## What it does per request
+
+1. Keeps the snapshot fresh. A Python server is a long-lived process, so the default is a daemon
+   poll thread at the cadence your tenant config sets (`poll_seconds`), with ETag/304 and gzip on
+   the wire. `CAMADA_SERVERLESS=1` switches to a per-request staleness check with no thread. Every
+   poll and event batch carries `x-camada-sdk: @camada/python/<version>`, and polls ask for
+   snapshot v5 (`x-camada-snapshot: 5`) — the container that carries your ordered custom rules.
+2. Resolves the client from the socket peer (`REMOTE_ADDR` / `scope["client"]`), combined with
+   `X-Forwarded-For` only under your tenant's trusted-proxy config (or `CAMADA_TRUSTED_PROXY`
+   locally). A forwarded header on its own is never the ip: any caller can set it.
+3. Enforces before anything else, beacon endpoints included: your ordered custom rules first (first
+   match wins; they read ip, path, user-agent and request headers), then allow → block → challenge.
+   A block answers `403 Forbidden` with `x-block-reason`, `x-block-version` and, when a rule
+   decided, `x-block-rule`; its event ships with `blk` (and `rl`). A `warn` rule passes and stamps
+   `wrn`; a `skip` rule passes with nothing stamped. Cold (no snapshot yet) passes: fail open.
+4. Challenge: a `challenge` verdict gets the self-contained proof-of-work page (or 403 JSON for a
+   non-HTML request); `POST /__camada/challenge` verifies the solution, sets `_cch` (bound to the
+   ip, one hour) and 302s back. A request whose ip cannot be resolved is never challenged.
+5. Serves the beacon: `GET /_cam/b.js` (the `@camada/browser` build, vendored) and `POST /_cam/fp`
+   (≤ 32 KB, relayed onto the event batch as a `sig: 1` row with the ip camada resolved). Both
+   fall through to your app when the tenant switched the beacon off.
+6. Runs your app with `x-rid` and the `_sfp` session cookie on its response, and when the response
+   is done ships one redacted event: method, host, path, scrubbed query, status, latency, header
+   names/sizes/order, the auth scheme (never the credential), cookie count (never values). An
+   exception in your app ships as `st: 500` and propagates unchanged.
+
+## Options
+
+`Camada(...)` keyword arguments; everything credential-shaped comes from the environment.
+
+| option | default | meaning |
+|---|---|---|
+| `env` | `os.environ` | where `CAMADA_*` are read from |
+| `transport` | urllib | the HTTP callable that reaches the analyst (tests inject a fake) |
+| `refresh_s` | server-steered | poll cadence; set, it is pinned |
+| `challenge` | `True` | serve the proof-of-work page for challenge verdicts (`CAMADA_CHALLENGE=0` too) |
+| `challenge_path` | `/__camada/challenge` | where the page posts its solution |
+| `snapshot_version` | `5` | 4 drops your custom rules; 3 the allow/challenge sides too |
+| `script_path` / `fp_path` | `/_cam/b.js` / `/_cam/fp` | the beacon endpoints; keep them in one directory |
+
+Env: `CAMADA_KEY` (or `CAMADA_TOKEN` + `CAMADA_SNAPSHOT_TOKEN`), `CAMADA_INGEST_URL`,
+`CAMADA_SNAPSHOT_URL`, `CAMADA_TRUSTED_PROXY` (`none | vercel | hops:N | cidrs:a,b`),
+`CAMADA_SERVERLESS=1`, `CAMADA_CHALLENGE=0`, and the kill switch `CAMADA_DISABLED=1` (checked per
+request; set at boot, no threads start at all).
+
+## The first-party beacon
+
+```python
+from camada.fastapi import script_tag        # camada.django: script_tag(request); camada.flask: script_tag()
+return HTMLResponse(f"<html><head>{script_tag(request)}</head>…")
+```
+
+The tag is `<script src="/_cam/b.js?r=<rid>" async>`, so the beacon joins the page view that
+served it. Move both paths with `script_path` / `fp_path` when `/_cam/` is not yours; the script
+derives the post path from its own URL, so the two must share a directory.
+
+## App-context events
+
+```python
+from camada.fastapi import track             # camada.django: track(request, ...); camada.flask: track(event, user=...)
+track(request, "login_failed", user=email)
+```
+
+The identifier is HMAC-hashed in-process with your ingest token; the raw value never reaches the
+queue. `track()` never raises and is a no-op on a request the middleware did not run for. The
+event name is free-form; the analyst's app-context rules read this vocabulary:
+
+| event | when |
+|---|---|
+| `login_failed` / `login_succeeded` | a login attempt settled; pass `user=` so attempts per account can be counted |
+| `signup` | an account was created |
+| `password_reset` | a reset was requested |
+| `mfa_failed` | a second factor was rejected |
+| `payment_failed` / `payment_succeeded` | a payment authorisation settled |
+| `coupon_failed` | a promo/voucher code was rejected |
+
+A route you gate yourself: `serve_challenge(request)` (Flask: `serve_challenge()`) returns the
+page as a framework response to return from the handler until the browser holds a valid `_cch`,
+then `None`.
+
+## What this tap can see
+
+`sdk-python` is an in-app tap: status, latency, session, the beacon's browser signals and your
+outcomes. Under ASGI the event also carries the wire's header order (`hord`); WSGI's `environ`
+loses it, which is why ASGI is the first-class tier. The analyst knows what this tap can see and
+never scores the absence of header order, ASN, country or a TLS fingerprint against a request;
+ASN and country it resolves itself. Enforcement at this position covers ip, path, user-agent and
+header conditions — ASN, country and TLS entries fail open in-app. `matches` patterns are JS
+regexes read by Python's `re` (named groups, `[^]` and `\cX` are translated, `\d`/`\w`/`\b` stay
+ASCII); a spelling `re` still rejects never matches here, while it does at the edge.
+
+## Deploying it
+
+- Every worker process polls its own snapshot (about 5 MB resident) and flushes its own batches;
+  the tenant's `poll_seconds` keeps the cadence honest across a fleet.
+- Threads do not survive a fork. Under gunicorn `--preload` or uWSGI the SDK notices the fork
+  (`os.register_at_fork`) and restarts its poll and flush threads in each worker.
+- Pending events drain at interpreter exit within half a second. No signal handlers are
+  installed — an app owns its own shutdown — so a worker killed by SIGTERM without one may drop
+  its last batch.
+- Serverless: `CAMADA_SERVERLESS=1`. A cold invocation fails open and catches up on the next one.
+
+## Fail open
+
+Every entry point runs inside the fail-open envelope: a dead ingest drops telemetry (logged at
+most once a minute), a corrupt snapshot keeps the previous one, a bug in the package costs the
+request its join, never its response. `CAMADA_DISABLED=1` bypasses everything.
+
+## Development
+
+```
+uv sync && uv run ruff check && uv run mypy && uv run pytest
+```
+
+The suite reads the golden snapshot fixtures from the `camada-core` sibling checkout and pins the
+vendored beacon to `camada-browser/dist/auto.global.js` (`npm run build` there first, then
+`python scripts/sync_beacon.py` after a beacon release). Both fail by name when the checkout is
+missing rather than skipping.
+
+[`camada-python-example`](../camada-python-example) is the hand-test bench (FastAPI under uvicorn on
+:3002), and `node scripts/e2e-sdk-python.mjs` in `camada/edge-analyst` drives it against a seeded
+local analyst over real HTTP, cold first request included.

camada-0.2.0/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "camada"
+dynamic = ["version"]
+description = "camada SDK for Python: inline enforcement of your snapshot (ordered custom rules, then allow, block, challenge), first-party beacon and proof-of-work challenge, batched event shipping. ASGI and WSGI middleware; Django, Flask and FastAPI integrations."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = []
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware",
+  "Topic :: Security",
+  "Framework :: Django",
+  "Framework :: Flask",
+  "Framework :: FastAPI",
+]
+
+[project.urls]
+Homepage = "https://camada.app"
+Repository = "https://github.com/camada-app/camada-python"
+Issues = "https://github.com/camada-app/camada-python/issues"
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "ruff>=0.6",
+  "mypy>=1.11",
+  "django>=4.2",
+  "flask>=3",
+  "fastapi>=0.110",
+  "httpx>=0.27",
+]
+
+[tool.hatch.version]
+path = "src/camada/version.py"
+
+[tool.uv]
+# uv fingerprints a path dependency by its pyproject alone; the version lives in version.py (hatch dynamic),
+# so a consumer's `uv lock` would keep the old number without this
+cache-keys = [{ file = "pyproject.toml" }, { file = "src/camada/version.py" }]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/camada"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/camada", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 140
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "W"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["camada"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/camada/beacon_js.py" = ["E501"]   # generated: one vendored JS string
+"tests/*" = ["E501"]
+
+[tool.mypy]
+strict = true
+files = ["src"]
+python_version = "3.10"
+
+[[tool.mypy.overrides]]
+module = ["django.*", "flask.*", "starlette.*", "fastapi.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+filterwarnings = [
+  "error",
+  # third-party test-client deprecations (starlette's httpx2 nudge, anyio alias), not ours
+  "ignore:.*httpx2.*",
+  "ignore::DeprecationWarning:starlette.*",
+  "ignore::DeprecationWarning:anyio.*",
+]

camada-0.2.0/src/camada/__init__.py

@@ -0,0 +1,47 @@
+"""camada for Python: inline enforcement of your tenant snapshot (ordered custom rules, then
+allow, block, challenge), a first-party proof-of-work challenge and beacon, app-context events,
+and batched wire events shipped off the request path. Fails open by design.
+
+Quickstart (env: CAMADA_KEY, plus CAMADA_INGEST_URL in dev):
+
+    # FastAPI / Starlette
+    from camada.fastapi import CamadaMiddleware
+    app.add_middleware(CamadaMiddleware)
+
+    # Django: MIDDLEWARE = ["camada.django.CamadaMiddleware", ...]
+    # Flask:  camada.flask.init_app(app)
+    # Any ASGI / WSGI app: camada.asgi.CamadaASGI(app) / camada.wsgi.CamadaWSGI(app)
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from .engine import Answer, Camada, Passed, Req, create_camada, engine_of
+from .version import SDK_ID, __version__
+
+__all__ = ["Answer", "Camada", "Passed", "Req", "SDK_ID", "__version__", "configure", "create_camada", "engine_for", "get_default"]
+
+_default: Camada | None = None
+
+
+def get_default(**opts: Any) -> Camada:
+    """The lazy singleton wired from the environment on first use (what the integrations share)."""
+    global _default
+    if _default is None:
+        _default = create_camada(**opts)
+    return _default
+
+
+def engine_for(ctx: Mapping[str, Any] | None) -> Camada:
+    """The engine that produced a request context, else the default: what the integrations resolve through."""
+    return engine_of(ctx) or get_default()
+
+
+def configure(**opts: Any) -> Camada:
+    """Replaces the default engine (stopping the old one) — for tests and explicit wiring."""
+    global _default
+    if _default is not None:
+        _default.stop()
+    _default = create_camada(**opts)
+    return _default