camada 0.2.0__py3-none-any.whl

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

camada/asgi.py

@@ -0,0 +1,149 @@
+# ASGI3 middleware: the first-class tier (scope["headers"] keeps the wire's header order), and
+# what FastAPI / Starlette sit on. A pure ASGI callable — never Starlette's BaseHTTPMiddleware,
+# which buffers streaming responses. Only http scopes are touched; lifespan and websocket pass.
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, MutableMapping
+from typing import Any
+
+from .engine import Answer, Camada, Passed, Req
+from .guarded import log_rate_limited
+
+Scope = MutableMapping[str, Any]
+Message = MutableMapping[str, Any]
+Receive = Callable[[], Awaitable[Message]]
+Send = Callable[[Message], Awaitable[None]]
+ASGIApp = Callable[[Scope, Receive, Send], Awaitable[None]]
+
+
+def req_from_scope(scope: Scope) -> Req:
+    headers = [(k.decode("latin-1").lower(), v.decode("latin-1")) for k, v in scope.get("headers") or ()]
+    query = (scope.get("query_string") or b"").decode("latin-1")
+    client, server = scope.get("client"), scope.get("server")
+    host = next((v for k, v in headers if k == "host"), "") or (str(server[0]) if server else "")   # the host name, never the port
+    return Req(
+        method=str(scope.get("method") or "GET"),
+        path=str(scope.get("path") or "/"),
+        query="?" + query if query else "",
+        host=host,
+        http_version=scope.get("http_version"),
+        peer=client[0] if client else None,
+        https=scope.get("scheme") == "https",
+        headers=headers,
+    )
+
+
+async def read_body(scope: Scope, receive: Receive, limit: int) -> tuple[bytes | None, Receive]:
+    """At most `limit` bytes (None when the declared or actual size exceeds it), plus a receive()
+    that replays what was consumed so an app the request falls through to still sees its body."""
+    try:
+        declared = int(next((v for k, v in scope.get("headers") or () if k == b"content-length"), b"0") or 0)
+    except ValueError:
+        declared = 0
+    chunks: list[Message] = []
+    if declared > limit:
+        return None, _replay(chunks, receive)
+    size = 0
+    over = False
+    while True:
+        m = await receive()
+        chunks.append(m)
+        if m["type"] != "http.request":
+            break
+        size += len(m.get("body") or b"")
+        if size > limit:
+            over = True
+            break
+        if not m.get("more_body"):
+            break
+    body = None if over else b"".join(bytes(m.get("body") or b"") for m in chunks if m["type"] == "http.request")
+    return body, _replay(chunks, receive)
+
+
+def _replay(chunks: list[Message], receive: Receive) -> Receive:
+    queued = list(chunks)
+
+    async def replay() -> Message:
+        return queued.pop(0) if queued else await receive()
+
+    return replay
+
+
+class CamadaASGI:
+    """`app.add_middleware(CamadaASGI)` (Starlette/FastAPI) or `app = CamadaASGI(app)`. Without an
+    engine it wires the lazy default from the environment on first request."""
+
+    def __init__(self, app: ASGIApp, engine: Camada | None = None, **opts: Any) -> None:
+        self.app = app
+        self._engine = engine
+        self._opts = opts
+
+    @property
+    def engine(self) -> Camada:
+        if self._engine is None:
+            from . import get_default
+
+            self._engine = get_default(**self._opts)
+        return self._engine
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+        eng = self.engine
+        try:
+            req = req_from_scope(scope)
+            limit = eng.wants_body(req.method, req.path)
+            body = None
+            if limit is not None:
+                body, receive = await read_body(scope, receive, limit)
+        except Exception as err:
+            log_rate_limited(err)
+            await self.app(scope, receive, send)
+            return
+        result = eng.handle(req, body)
+        if isinstance(result, Answer):
+            headers = [(k.encode("latin-1"), v.encode("latin-1")) for k, v in result.headers]
+            headers.append((b"content-length", str(len(result.body)).encode()))
+            await send({"type": "http.response.start", "status": result.status, "headers": headers})
+            await send({"type": "http.response.body", "body": result.body})
+            return
+        await self._run(scope, receive, send, result)
+
+    async def _run(self, scope: Scope, receive: Receive, send: Send, p: Passed) -> None:
+        if p.ctx is not None:
+            scope["camada"] = p.ctx
+        state = {"status": 500, "fired": False}
+
+        def finish(status: int) -> None:
+            if state["fired"] or not p.on_finish:
+                return
+            state["fired"] = True
+            if p.ctx is not None and p.ctx.get("_req") is not None:
+                route = scope.get("route")
+                p.ctx["_req"].route = getattr(route, "path", None) if route is not None else None
+            p.on_finish(status)
+
+        async def send_wrapper(m: Message) -> None:
+            if m["type"] == "http.response.start":
+                try:
+                    state["status"] = int(m.get("status", 200))
+                    headers = list(m.get("headers") or [])
+                    if p.rid:
+                        headers.append((b"x-rid", p.rid.encode()))
+                    if p.set_cookie:
+                        headers.append((b"set-cookie", p.set_cookie.encode("latin-1")))
+                    m["headers"] = headers
+                except Exception as err:
+                    log_rate_limited(err)
+            await send(m)
+            if m["type"] == "http.response.body" and not m.get("more_body"):
+                finish(int(state["status"]))
+
+        try:
+            await self.app(scope, receive, send_wrapper)
+        except BaseException:
+            finish(500)
+            raise
+        finally:
+            finish(int(state["status"]))

camada/beacon_js.py

@@ -0,0 +1,6 @@
+# GENERATED by scripts/sync_beacon.py — do not edit. The first-party beacon (@camada/browser's
+# dist/auto.global.js) vendored as a string: served at /_cam/b.js with no runtime file read.
+# tests/test_beacon_js.py pins it to the sibling build byte for byte.
+BEACON_VERSION = '0.2.0'
+BEACON_SHA256 = 'f0de88bef775d44b76e363d9cb6b87da7bb908172d686921326b635ff03f012b'
+BEACON_JS = '"use strict";(()=>{var k="0.2.0";var _="@camada/browser";var b=`${_}/${k}`;function n(t){try{return t()}catch{return null}}function x(t){let e=2166136261;for(let i=0;i<t.length;i++)e^=t.charCodeAt(i),e=Math.imul(e,16777619);return(e>>>0).toString(16)}function M(){let t=document.createElement("canvas");t.width=240,t.height=60;let e=t.getContext("2d");return e?(e.textBaseline="alphabetic",e.fillStyle="#f60",e.fillRect(120,5,60,20),e.fillStyle="#069",e.font="15px Arial",e.fillText("Sfp\\u2603 1.0",2,15),e.fillStyle="rgba(102,204,0,0.7)",e.font="17px Times",e.fillText("Sfp\\u2603 1.0",4,45),x(t.toDataURL())):null}function R(){let t=document.createElement("canvas"),e=t.getContext("webgl")||t.getContext("experimental-webgl");if(!e)return null;let i=e.getExtension("WEBGL_debug_renderer_info");return{v:i?e.getParameter(i.UNMASKED_VENDOR_WEBGL):e.getParameter(e.VENDOR),r:i?e.getParameter(i.UNMASKED_RENDERER_WEBGL):e.getParameter(e.RENDERER)}}function S(){return x([Math.tan(-1e300),Math.sinh(1),Math.expm1(1),Math.cbrt(100),Math.log1p(10),Math.atanh(.5)].join("|"))}var N=/^\\$?cdc_|^__webdriver|^__selenium|^__nightmare|^__playwright|^callPhantom/,L=/^\\$?cdc_|^__webdriver|^__selenium|^__nightmare|^__playwright|^callPhantom|^_phantom/;function j(){let t=document,e=navigator,i=window,o=0;for(let s in t)N.test(s)&&o++;for(let s in i)L.test(s)&&o++;return{wd:e.webdriver===!0?1:0,cdc:o,chrome:typeof i.chrome<"u"?1:0,plugins:e.plugins?e.plugins.length:-1,langs:e.languages?e.languages.length:-1,outer:window.outerWidth===0&&window.outerHeight===0?1:0,perm:n(()=>Notification.permission),pdf:typeof e.pdfViewerEnabled=="boolean"?e.pdfViewerEnabled?1:0:-1,err:n(()=>{try{null.x}catch(s){let c=s.stack;return c?c.split(`\n`).length:0}})}}function T({endpoint:t,rid:e}){let i=e||null,o=performance.now(),s=0,c=0,m=0,h=0,f=0,u=null;function l(){u===null&&(u=Math.round(performance.now()-o))}addEventListener("mousemove",()=>{s++,l()},{passive:!0}),addEventListener("scroll",()=>{c++,l()},{passive:!0}),addEventListener("keydown",()=>{m++,l()},{passive:!0}),addEventListener("touchstart",()=>{h++,l()},{passive:!0}),addEventListener("click",()=>{f++,l()},{passive:!0});function w(){let r=navigator,a=n(()=>performance.getEntriesByType("navigation")[0]),D=n(()=>{let p=performance.getEntriesByType("paint");return p.length?Math.round(p[p.length-1].startTime):null}),d=n(()=>r.connection)||{};return{sdk:b,rid:i,ts:Date.now(),scr:n(()=>[screen.width,screen.height,screen.availWidth,screen.availHeight,screen.colorDepth]),win:n(()=>[window.innerWidth,window.innerHeight,window.outerWidth,window.outerHeight]),dpr:n(()=>window.devicePixelRatio),tz:n(()=>Intl.DateTimeFormat().resolvedOptions().timeZone),tzo:n(()=>new Date().getTimezoneOffset()),lang:n(()=>r.language),langs:n(()=>r.languages?Array.prototype.slice.call(r.languages,0,5):null),plat:n(()=>r.platform),cores:n(()=>r.hardwareConcurrency),mem:n(()=>r.deviceMemory),touch:n(()=>r.maxTouchPoints),ua:n(()=>r.userAgent),dnt:n(()=>r.doNotTrack),cookies:n(()=>r.cookieEnabled?1:0),conn:n(()=>[d.effectiveType,d.rtt,d.downlink,d.saveData?1:0]),gl:n(R),cv:n(M),mf:n(S),auto:n(j),vis:n(()=>document.visibilityState),focus:n(()=>document.hasFocus()?1:0),timing:a?[Math.round(a.domContentLoadedEventEnd),Math.round(a.loadEventEnd),Math.round(a.responseEnd-a.requestStart)]:null,paint:D,input:{moves:s,scrolls:c,keys:m,touches:h,clicks:f,first:u,at:Math.round(performance.now()-o)}}}function v(r){let a=JSON.stringify(r?Object.assign(w(),{hi:r}):w());navigator.sendBeacon&&navigator.sendBeacon(t,new Blob([a],{type:"application/json"}))||fetch(t,{method:"POST",body:a,keepalive:!0,headers:{"content-type":"application/json"}}).catch(()=>{})}let g=navigator.userAgentData,E=g&&g.getHighEntropyValues?g.getHighEntropyValues(["architecture","bitness","model","platformVersion","fullVersionList"]).catch(()=>null):Promise.resolve(null);setTimeout(()=>{E.then(v)},2e3),addEventListener("pagehide",()=>{E.then(r=>{v(r)})},{once:!0})}function O(t){let e=new URL(t,"http://_"),i=e.pathname.split("/");return i[i.length-1]="fp",{endpoint:i.join("/"),rid:e.searchParams.get("r")}}(function(){try{let t=document.currentScript,e=t&&t.src;if(!e)return;let{endpoint:i,rid:o}=O(e);T({endpoint:i,rid:o})}catch{}})();})();\n'

camada/challenge/format.py

@@ -0,0 +1,113 @@
+# Wire constants and pure helpers for the SDK-served challenge (contracts §D2), ported from
+# @camada/core src/challenge/format.ts. Nothing here does crypto; verify.py supplies HMAC and
+# SHA-256 from the stdlib, so the format has exactly one definition across the family.
+from __future__ import annotations
+
+import hmac
+import json
+from urllib.parse import unquote
+
+CHALLENGE_COOKIE = "_cch"
+CHALLENGE_TTL_MS = 3_600_000   # 1 h (contract)
+POW_BITS = 16                  # leading zero bits of SHA-256(f"{nonce}.{solution}")
+NONCE_HEX = 32                 # the nonce is the first 32 hex chars of the HMAC
+_DAY_MS = 86_400_000
+_MAX_RETURN_TO = 2048
+_MAX_SOLUTION = 32
+
+
+def utc_day(now_ms: int) -> int:
+    return now_ms // _DAY_MS
+
+
+# Domain-separated messages: a nonce HMAC can never be replayed as a cookie HMAC.
+def nonce_message(ip: str | None, day: int) -> str:
+    return f"camada-challenge-nonce|{ip or ''}|{day}"
+
+
+def token_message(ip: str | None, exp: int) -> str:
+    return f"camada-challenge-token|{ip or ''}|{exp}"
+
+
+def split_token(value: str | None) -> tuple[int, str] | None:
+    if not value:
+        return None
+    dot = value.find(".")
+    if dot <= 0:
+        return None
+    try:
+        exp = int(value[:dot])
+    except ValueError:
+        return None
+    mac = value[dot + 1 :]
+    return (exp, mac) if mac else None
+
+
+def safe_equal(a: str, b: str) -> bool:
+    """Constant-time for equal-length strings; length itself is not a secret here."""
+    return len(a) == len(b) and hmac.compare_digest(a.encode(), b.encode())
+
+
+def pow_ok(hex_digest: str, bits: int = POW_BITS) -> bool:
+    """True when the hex digest starts with `bits` zero bits."""
+    nibbles, rest = bits >> 2, bits & 3
+    if len(hex_digest) < nibbles + (1 if rest else 0):
+        return False
+    if any(hex_digest[i] != "0" for i in range(nibbles)):
+        return False
+    if rest == 0:
+        return True
+    try:
+        v = int(hex_digest[nibbles], 16)
+    except ValueError:
+        return False
+    return (v >> (4 - rest)) == 0
+
+
+def solution_shape_ok(solution: str | None) -> bool:
+    return bool(solution) and len(solution or "") <= _MAX_SOLUTION
+
+
+def challenge_cookie(value: str, secure: bool) -> str:
+    return f"{CHALLENGE_COOKIE}={value}; Path=/; Max-Age={CHALLENGE_TTL_MS // 1000}; HttpOnly; SameSite=Lax{'; Secure' if secure else ''}"
+
+
+def safe_return_to(raw: str | None) -> str:
+    """Only a printable-ASCII same-site absolute path survives: never an absolute URL, a
+    protocol-relative '//host' redirect, a control character, or something absurdly long."""
+    if not raw or len(raw) > _MAX_RETURN_TO:
+        return "/"
+    if raw[0] != "/" or (len(raw) > 1 and raw[1] in "/\\"):
+        return "/"
+    if any(not (0x21 <= ord(c) <= 0x7E) for c in raw):
+        return "/"
+    return raw
+
+
+def wants_html(accept: str | None, sec_fetch_dest: str | None) -> bool:
+    """A challenge page is only worth serving to a top-level HTML navigation (contract §D2)."""
+    if not accept or "text/html" not in accept:
+        return False
+    return not sec_fetch_dest or sec_fetch_dest == "document"
+
+
+def escape_attr(s: str) -> str:
+    return s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").replace('"', "&quot;").replace("'", "&#39;")
+
+
+def escape_script(s: str) -> str:
+    """Safe to drop inside an inline <script>: `<` is escaped so no value can close the element early."""
+    return json.dumps(s).replace("<", "\\u003c")
+
+
+def parse_form_body(body: str) -> dict[str, str]:
+    """application/x-www-form-urlencoded, last value wins. Never raises on junk."""
+    out: dict[str, str] = {}
+    for pair in body.split("&"):
+        if not pair:
+            continue
+        eq = pair.find("=")
+        k = pair if eq == -1 else pair[:eq]
+        v = "" if eq == -1 else pair[eq + 1 :]
+        out[unquote(k.replace("+", " "))] = unquote(v.replace("+", " "))
+    return out

camada/challenge/page.py

@@ -0,0 +1,104 @@
+# The 403 challenge page: one self-contained HTML document, no external assets, no-store —
+# byte-for-byte the page @camada/core serves (src/challenge/page.ts). The inline solver hunts a
+# counter whose SHA-256(`${nonce}.${counter}`) starts with 16 zero bits (~65k hashes, tens of
+# milliseconds), fills the hidden form and submits it. The form POST means the browser follows
+# the verify endpoint's 302 natively, so the cookie is set and the original URL is re-fetched
+# without any fetch/CORS/cookie subtleties.
+#
+# The page carries its own SHA-256 rather than calling crypto.subtle: subtle is undefined on
+# non-secure origins (plain http on a LAN host), and 65k awaited digests would be slow anyway.
+from __future__ import annotations
+
+from .format import POW_BITS, escape_attr, escape_script
+
+# FIPS 180-4 round constants (cube roots of the first 64 primes).
+_K = (
+    "0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5,"
+    "0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174,"
+    "0xe49b69c1,0xefbe4786,0xfc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da,"
+    "0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x6ca6351,0x14292967,"
+    "0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85,"
+    "0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070,"
+    "0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3,"
+    "0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2"
+)
+
+# One SHA-256 over an ASCII string. Returns the 8 state words; the solver reads H[0] only
+# (16 leading zero bits === H[0] >>> 16 === 0, which is exactly the server's pow_ok(hex, 16)).
+_SOLVER = (
+    "\nvar __camadaK=[" + _K + "];\n"
+    "function __camadaRr(x,n){return (x>>>n)|(x<<(32-n))}\n"
+    "function __camadaSha256Words(msg){\n"
+    "  var K=__camadaK,rr=__camadaRr,l=msg.length,wl=(((l+9+63)>>6)<<4),M=new Uint32Array(wl),i;\n"
+    "  for(i=0;i<l;i++)M[i>>2]|=(msg.charCodeAt(i)&255)<<(24-(i%4)*8);\n"
+    "  M[l>>2]|=0x80<<(24-(l%4)*8);\n"
+    "  M[wl-1]=l*8;\n"
+    "  var H=[0x6a09e667,0xbb67ae85,0x3c6ef372,0xa54ff53a,0x510e527f,0x9b05688c,0x1f83d9ab,0x5be0cd19];\n"
+    "  var W=new Uint32Array(64),bi,t;\n"
+    "  for(bi=0;bi<wl;bi+=16){\n"
+    "    for(t=0;t<16;t++)W[t]=M[bi+t];\n"
+    "    for(t=16;t<64;t++){var x=W[t-15],y=W[t-2];\n"
+    "      W[t]=(W[t-16]+(rr(x,7)^rr(x,18)^(x>>>3))+W[t-7]+(rr(y,17)^rr(y,19)^(y>>>10)))>>>0}\n"
+    "    var a=H[0],b=H[1],c=H[2],d=H[3],e=H[4],f=H[5],g=H[6],h=H[7];\n"
+    "    for(t=0;t<64;t++){\n"
+    "      var t1=(h+(rr(e,6)^rr(e,11)^rr(e,25))+((e&f)^(~e&g))+K[t]+W[t])>>>0;\n"
+    "      var t2=((rr(a,2)^rr(a,13)^rr(a,22))+((a&b)^(a&c)^(b&c)))>>>0;\n"
+    "      h=g;g=f;f=e;e=(d+t1)>>>0;d=c;c=b;b=a;a=(t1+t2)>>>0}\n"
+    "    H[0]=(H[0]+a)>>>0;H[1]=(H[1]+b)>>>0;H[2]=(H[2]+c)>>>0;H[3]=(H[3]+d)>>>0;\n"
+    "    H[4]=(H[4]+e)>>>0;H[5]=(H[5]+f)>>>0;H[6]=(H[6]+g)>>>0;H[7]=(H[7]+h)>>>0}\n"
+    "  return H}\n"
+    "function __camadaSha256Hex(msg){\n"
+    "  var H=__camadaSha256Words(msg),s='',i;\n"
+    "  for(i=0;i<8;i++)s+=('00000000'+H[i].toString(16)).slice(-8);\n"
+    "  return s}\n"
+)
+
+_STYLE = (
+    ":root{color-scheme:light}\n"
+    "body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;background:#fafafa;color:#1a1a1a;"
+    "font:16px/1.5 system-ui,-apple-system,Segoe UI,Roboto,sans-serif}\n"
+    "main{max-width:28rem;padding:2rem;text-align:center}\n"
+    "h1{font-size:1.25rem;margin:0 0 .5rem}\n"
+    "p{margin:.25rem 0;color:#555}\n"
+    ".bar{margin:1.5rem auto 0;width:12rem;height:4px;border-radius:2px;background:#e5e5e5;overflow:hidden}\n"
+    ".bar i{display:block;height:100%;width:30%;background:#1a1a1a;animation:camada-slide 1.1s ease-in-out infinite}\n"
+    "@keyframes camada-slide{0%{transform:translateX(-120%)}100%{transform:translateX(400%)}}\n"
+)
+
+
+def challenge_page(*, nonce: str, action: str, to: str, bits: int = POW_BITS) -> str:
+    """`action` is the verify endpoint path; `to` has already been through safe_return_to."""
+    bits = min(32, max(1, bits))   # shift 32-bits must stay in range
+    return (
+        "<!doctype html>\n"
+        '<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">\n'
+        "<title>Checking your browser</title>\n"
+        "<style>\n" + _STYLE + "</style></head>\n"
+        "<body>\n"
+        "<main>\n"
+        "<h1>Checking your browser</h1>\n"
+        '<p id="camada-msg">This takes a moment. It runs entirely in your browser.</p>\n'
+        "<noscript><p>JavaScript is required to continue.</p></noscript>\n"
+        '<div class="bar"><i></i></div>\n'
+        "</main>\n"
+        f'<form id="camada-f" method="POST" action="{escape_attr(action)}">\n'
+        f'<input type="hidden" name="nonce" value="{escape_attr(nonce)}">\n'
+        '<input type="hidden" name="solution" id="camada-s">\n'
+        f'<input type="hidden" name="to" value="{escape_attr(to)}">\n'
+        "</form>\n"
+        "<script>" + _SOLVER + "\n"
+        "(function(){\n"
+        "  if(typeof window==='undefined'||window.__camadaAutostart===false)return;\n"
+        f"  var nonce={escape_script(nonce)},shift={32 - bits};\n"
+        "  function go(){\n"
+        "    for(var n=0;n<5000000;n++){\n"
+        "      if((__camadaSha256Words(nonce+'.'+n)[0]>>>shift)===0){\n"
+        "        document.getElementById('camada-s').value=String(n);\n"
+        "        document.getElementById('camada-f').submit();\n"
+        "        return}}\n"
+        "    document.getElementById('camada-msg').textContent='Could not complete the check. Please reload.'}\n"
+        "  setTimeout(go,30);\n"
+        "})();\n"
+        "</script>\n"
+        "</body></html>"
+    )

camada/challenge/verify.py

@@ -0,0 +1,75 @@
+# The challenge kit over the stdlib's HMAC-SHA256 and SHA-256, ported from @camada/core
+# src/challenge/verify.ts. Synchronous, so the engine's handle() stays a plain function.
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+from .format import (
+    CHALLENGE_TTL_MS,
+    NONCE_HEX,
+    nonce_message,
+    pow_ok,
+    safe_equal,
+    solution_shape_ok,
+    split_token,
+    token_message,
+    utc_day,
+)
+
+
+class ChallengeKit:
+    __slots__ = ("_secret",)
+
+    def __init__(self, secret: str) -> None:
+        self._secret = secret.encode()
+
+    def _hmac(self, msg: str) -> str:
+        return hmac.new(self._secret, msg.encode(), hashlib.sha256).hexdigest()
+
+    def _at(self, ip: str, day: int) -> str:
+        return self._hmac(nonce_message(ip, day))[:NONCE_HEX]
+
+    def nonce(self, ip: str, now_ms: int) -> str:
+        """Stateless per-(ip, UTC day) nonce; the verify endpoint recomputes it, nothing is stored."""
+        return self._at(ip, utc_day(now_ms))
+
+    # Yesterday still passes: a solve started before midnight UTC must not be thrown away.
+    # So one solved (nonce, solution) pair is replayable from its own IP for up to ~48 h,
+    # minting a fresh 1 h cookie each time. That is the price of a stateless nonce (§D2) and
+    # it is deliberate — do not "fix" it into something that needs shared server state.
+    def nonce_valid(self, ip: str | None, now_ms: int, nonce: str | None) -> bool:
+        if not ip or not nonce or len(nonce) != NONCE_HEX:
+            return False
+        day = utc_day(now_ms)
+        return safe_equal(nonce, self._at(ip, day)) or safe_equal(nonce, self._at(ip, day - 1))
+
+    def issue(self, ip: str, now_ms: int) -> str:
+        exp = now_ms + CHALLENGE_TTL_MS
+        return f"{exp}.{self._hmac(token_message(ip, exp))}"
+
+    # A null ip is refused outright: without one the token is bound to nothing, so a single
+    # solve would mint a cookie every other unidentified client could present. Adapters must
+    # fail open (serve no challenge) rather than challenge a client they cannot identify.
+    def token_valid(self, ip: str | None, now_ms: int, cookie_value: str | None) -> bool:
+        if not ip:
+            return False
+        t = split_token(cookie_value)
+        if t is None:
+            return False
+        exp, mac = t
+        if exp <= now_ms or exp > now_ms + CHALLENGE_TTL_MS:
+            return False
+        return safe_equal(mac, self._hmac(token_message(ip, exp)))
+
+    def solution_ok(self, nonce: str, solution: str | None) -> bool:
+        """Proof of work ONLY. Never call it without a passing nonce_valid() for the same nonce."""
+        return solution_shape_ok(solution) and pow_ok(hashlib.sha256(f"{nonce}.{solution}".encode()).hexdigest())
+
+    def verify(self, ip: str | None, now_ms: int, nonce: str | None, solution: str | None) -> bool:
+        """The whole submission: the nonce is ours and unexpired, and the work is done."""
+        return self.nonce_valid(ip, now_ms, nonce) and self.solution_ok(nonce or "", solution)
+
+
+def create_challenge(secret: str) -> ChallengeKit:
+    return ChallengeKit(secret)

camada/config.py

@@ -0,0 +1,59 @@
+# Configuration shapes shared by the client and the engine. `parse_key` splits CAMADA_KEY, and
+# `RemoteConfig` is what GET /snapshot hands back in x-camada-config (whitelisted server-side).
+from __future__ import annotations
+
+from typing import Any, TypedDict, cast
+
+
+class TrustedProxy(TypedDict, total=False):
+    """Mirrors the server-validated tenant config (edge-analyst src/tenant-config.js):
+    {mode: none} | {mode: hops, hops: N} | {mode: cidrs, cidrs: [...]} | {mode: vercel}."""
+
+    mode: str
+    hops: int
+    cidrs: list[str]
+
+
+class RemoteConfig(TypedDict, total=False):
+    tenant: str
+    beacon: bool
+    sample: float
+    exclude: list[str]
+    trusted_proxy: TrustedProxy
+    poll_seconds: float
+
+
+def parse_key(key: str | None) -> tuple[str, str] | None:
+    """CAMADA_KEY is `<ingest_token>.<snap_token>` (printed by reconcile instructions and seed)."""
+    if not key:
+        return None
+    dot = key.find(".")
+    if dot <= 0 or dot == len(key) - 1:
+        return None
+    return key[:dot], key[dot + 1 :]
+
+
+def parse_trusted_proxy_env(v: str | None) -> TrustedProxy | None:
+    """CAMADA_TRUSTED_PROXY: none | vercel | hops:N | cidrs:a,b. Unset or malformed returns None,
+    which callers treat as "defer to the server-delivered tenant config", never as trust."""
+    if not v:
+        return None
+    if v == "none":
+        return {"mode": "none"}
+    if v == "vercel":
+        return {"mode": "vercel"}
+    if v.startswith("hops:"):
+        try:
+            hops = int(v[5:])
+        except ValueError:
+            return None
+        return {"mode": "hops", "hops": hops} if hops >= 1 else None
+    if v.startswith("cidrs:"):
+        cidrs = [c.strip() for c in v[6:].split(",") if c.strip()]
+        return {"mode": "cidrs", "cidrs": cidrs} if cidrs else None
+    return None
+
+
+def remote_config(raw: Any) -> RemoteConfig | None:
+    """The parsed x-camada-config header; anything but a JSON object is ignored (previous kept)."""
+    return cast(RemoteConfig, raw) if isinstance(raw, dict) else None

camada/constants.py

@@ -0,0 +1,19 @@
+# Tap identifier this SDK claims on the wire. The server validates against its own enum and
+# derives the capability mask itself (edge-analyst src/capabilities.js): an SDK can never grant
+# itself capability bits, only name its position — and an unknown name is silently read as a
+# proxy, so this literal is load-bearing.
+TAP = "sdk-python"
+
+DEFAULT_REFRESH_S = 30.0
+# 5 carries the tenant's ordered custom rules (§D3); a tenant without one is answered with the next container down.
+DEFAULT_SNAPSHOT_VERSION = 5
+KILL_SWITCH_ENV = "CAMADA_DISABLED"
+
+SCRIPT_PATH = "/_cam/b.js"
+FP_PATH = "/_cam/fp"
+FP_MAX = 32 * 1024                 # matches the server's /fp cap: never accept what ingest will 413
+CHALLENGE_PATH = "/__camada/challenge"
+BODY_MAX = 4 * 1024                # the verify form is ~120 bytes; anything larger is not ours
+
+SESSION_COOKIE = "_sfp"            # same cookie as the edge collector: sid/ns comparable across taps
+SESSION_MAX_AGE = 2592000          # 30 days