pyweb-stack 0.1.0__py3-none-any.whl

pyweb/runtime/server/__init__.py

@@ -0,0 +1,445 @@
+"""Server runtime: routing, SSR, typed RPC dispatcher, static assets."""
+
+from __future__ import annotations
+
+import html as _html
+import inspect
+import json
+import re
+import uuid
+
+
+class Request:
+    def __init__(self, method, path, headers=None, body=b"", cookies=None):
+        self.method = method.upper()
+        self.path = path
+        self.headers = headers or {}
+        self.body = body
+        if cookies is None:
+            cookies = {}
+            raw = next((v for k, v in self.headers.items() if k.lower() == "cookie"), "")
+            for pair in (raw or "").split(";"):
+                name, sep, value = pair.partition("=")
+                if sep and name.strip():
+                    cookies[name.strip()] = value.strip().strip('"')
+        self.cookies = cookies
+        self.id = uuid.uuid4().hex[:12]
+
+
+class Response:
+    def __init__(self, status=200, body="", headers=None):
+        self.status = status
+        self.body = body
+        self.headers = headers or {}
+
+
+_POOL = None
+
+
+def _rpc_error():
+    from pyweb.rpc import RPCError
+    return RPCError
+
+
+async def _awaited(aw):
+    return await aw
+
+
+def _rpc_pool():
+    global _POOL
+    if _POOL is None:
+        import concurrent.futures as _fut
+        _POOL = _fut.ThreadPoolExecutor(max_workers=32, thread_name_prefix="pyweb-rpc")
+    return _POOL
+
+
+def _coerce(value, ann):
+    if ann in ("int", "Integer"):
+        return int(value)
+    if ann in ("float", "Float", "Decimal"):
+        return float(value)
+    if ann in ("bool", "Boolean"):
+        if isinstance(value, str):
+            return value.lower() in ("1", "true", "yes")
+        return bool(value)
+    return value
+
+
+class Server:
+    #: Default cap for RPC request bodies (1 MiB). Bodies beyond this
+    #: are rejected with ``413 body-too-large`` before JSON parsing.
+    MAX_BODY = 1_048_576
+
+    def __init__(self, compiled=None, *, auth_secret=None, csrf_secret=None,
+                 rate_limit=None, rpc_timeout=None, tracer=None,
+                 logger=None, max_body=None, app=None, debug=False,
+                 secure_cookies=False):
+        if compiled is None:
+            compiled = app.compiled if app is not None else {"pages": {}, "rpc": []}
+        self.app = app
+        self.debug = debug
+        self.secure_cookies = secure_cookies
+        self.compiled = compiled
+        self.rpc_impls: dict[str, object] = {}
+        self.routes: list[tuple[re.Pattern, str]] = []
+        for name, page in compiled["pages"].items():
+            pat = "^" + re.sub(r"\{(\w+)\}", r"(?P<\1>[^/]+)", page["route"]) + "$"
+            self.routes.append((re.compile(pat), name))
+        # Production RPC controls (all optional; secure defaults when set).
+        self.auth_secret = auth_secret
+        self.csrf_secret = csrf_secret
+        self.rate_limit = rate_limit  # RateLimiter or None
+        self.rpc_timeout = rpc_timeout  # seconds or None
+        self.max_body = self.MAX_BODY if max_body is None else max_body
+        self.tracer = tracer
+        self.logger = logger
+        if app is not None:
+            for fn in app.rpc.values():
+                self.register_rpc(fn)
+
+    def register_rpc(self, fn):
+        self.rpc_impls[fn.__name__] = fn
+
+    def _trace_ctx(self, req: Request):
+        from pyweb import rpc as _rpc
+        parsed = _rpc.parse_traceparent(req.headers.get("traceparent"))
+        trace_id = parsed[0] if parsed else uuid.uuid4().hex
+        span_id = uuid.uuid4().hex[:16]
+        return trace_id, _rpc.make_traceparent(trace_id, span_id)
+
+    def _err(self, code, message, *, details=None, trace_id=None,
+             traceparent=None, retry_after=None):
+        from pyweb import rpc as _rpc
+        if isinstance(code, str):
+            body = {"error": {"code": code, "message": message,
+                              "details": details or {}}}
+            status = _rpc.status_for(code)
+        else:  # numeric status with the same envelope shape
+            body = {"error": {"code": f"http_{code}", "message": message,
+                              "details": details or {}}}
+            status = code
+        headers = {"Content-Type": "application/json"}
+        if trace_id:
+            headers["X-Request-Id"] = trace_id
+        if traceparent:
+            headers["traceparent"] = traceparent
+        if retry_after:
+            headers["Retry-After"] = str(retry_after)
+        return Response(status, json.dumps(body), headers)
+
+    def _check_rpc_access(self, req: Request, fn):
+        """Auth + CSRF + rate-limit gate. Returns None (allow) or Response."""
+        from pyweb import rpc as _rpc
+        need_auth = getattr(fn, "__pyweb_auth__", False)
+        need = getattr(fn, "__pyweb_permissions__", [])
+        csrf_exempt = getattr(fn, "__pyweb_csrf_exempt__", False)
+        if need_auth or need:
+            secret = self.auth_secret
+            if not secret:
+                return None  # no secret configured: decorators are advisory
+            from pyweb import auth as _auth
+            session = _auth.session_from_request(req, secret)
+            if session is None or "sub" not in session:
+                return self._err(_rpc.Code.AUTH, "authentication required")
+            if need and not _auth.can(session.get("roles", []), fn):
+                return self._err(_rpc.Code.FORBIDDEN,
+                                 f"missing permission: {need}")
+            if self.csrf_secret and not csrf_exempt:
+                token = req.headers.get("X-CSRF-Token", "")
+                if not _auth.verify_csrf(self.csrf_secret,
+                                         session.get("sid", session.get("sub", "")),
+                                         token):
+                    return self._err(_rpc.Code.CSRF, "invalid CSRF token")
+        if self.rate_limit is not None:
+            key = req.headers.get("X-Forwarded-For",
+                                  req.cookies.get("pyweb_session", "anon"))
+            ok, retry = self.rate_limit.allow(
+                f"{fn.__name__}:{key}")
+            if not ok:
+                return self._err(_rpc.Code.RATE_LIMIT, "rate limit exceeded",
+                                 retry_after=retry)
+        return None
+
+    def _validate(self, fn, args: dict):
+        sig = inspect.signature(fn)
+        out = {}
+        for pname, param in sig.parameters.items():
+            ann = getattr(param.annotation, "__name__", str(param.annotation)) if param.annotation is not inspect.Parameter.empty else "Any"
+            if pname in args:
+                try:
+                    out[pname] = _coerce(args[pname], ann)
+                except (ValueError, TypeError):
+                    raise TypeError(f"{fn.__name__}.{pname} expects {ann}")
+                if "Email" in ann and "@" not in str(out[pname]):
+                    raise ValueError(f"{fn.__name__}.{pname} must be a valid email")
+            elif param.default is inspect.Parameter.empty:
+                raise TypeError(f"{fn.__name__} missing required argument {pname!r}")
+        return out
+
+    def handle_rpc(self, req: Request):
+        from pyweb import rpc as _rpc
+        m = re.match(r"^/__pyweb/rpc/(\w+)$", req.path)
+        if not m:
+            return None
+        trace_id, traceparent = self._trace_ctx(req)
+        span = None
+        if self.tracer is not None:
+            span = self.tracer.start(f"rpc.{m.group(1)}", trace_id=trace_id)
+        try:
+            name = m.group(1)
+            fn = self.rpc_impls.get(name)
+            if fn is None:
+                return self._err(_rpc.Code.NOT_FOUND, f"unknown rpc {name}",
+                                 trace_id=trace_id, traceparent=traceparent)
+            gate = self._check_rpc_access(req, fn)
+            if gate is not None:
+                gate.headers.setdefault("X-Request-Id", trace_id)
+                gate.headers["traceparent"] = traceparent
+                return gate
+            hdr = {k.lower(): v for k, v in (req.headers or {}).items()}
+            ctype = hdr.get("content-type", "")
+            if ctype and "json" not in ctype.lower():
+                # Browsers can only send cross-site requests without a CORS
+                # preflight using form encodings; requiring JSON blocks them.
+                return self._err(415, "RPC requests must be application/json",
+                                 trace_id=trace_id, traceparent=traceparent)
+            origin = hdr.get("origin")
+            host = hdr.get("x-forwarded-host") or hdr.get("host")
+            if origin and host and origin != "null":
+                from urllib.parse import urlparse as _urlparse
+                if _urlparse(origin).netloc != host:
+                    return self._err(_rpc.Code.CSRF, "cross-origin RPC call rejected",
+                                     trace_id=trace_id, traceparent=traceparent)
+            if self.max_body is not None and len(req.body or b"") > self.max_body:
+                return self._err(413, "request body too large",
+                                 trace_id=trace_id, traceparent=traceparent)
+            try:
+                payload = json.loads(req.body or b"{}")
+            except json.JSONDecodeError:
+                return self._err(_rpc.Code.VALIDATION, "invalid JSON",
+                                 trace_id=trace_id, traceparent=traceparent)
+            args = payload.get("args", {}) if isinstance(payload, dict) else {}
+            try:
+                clean = self._validate(fn, args if isinstance(args, dict) else {})
+            except (TypeError, ValueError) as exc:
+                return self._err(_rpc.Code.VALIDATION, str(exc),
+                                 trace_id=trace_id, traceparent=traceparent)
+            try:
+                if self.rpc_timeout:
+                    result = self._call_with_timeout(fn, clean)
+                else:
+                    result = fn(**clean)
+                if inspect.isawaitable(result):
+                    import asyncio
+                    result = asyncio.run(_awaited(result))
+            except TimeoutError:
+                return self._err(_rpc.Code.TIMEOUT,
+                                 f"{name} exceeded {self.rpc_timeout}s",
+                                 trace_id=trace_id, traceparent=traceparent)
+            except _rpc.RPCError as exc:
+                return self._err(exc.code, str(exc), details=exc.details,
+                                 trace_id=trace_id, traceparent=traceparent)
+            except (TypeError, ValueError) as exc:
+                return self._err(_rpc.Code.VALIDATION, str(exc),
+                                 trace_id=trace_id, traceparent=traceparent)
+            except Exception as exc:  # noqa: BLE001
+                if self.logger is not None:
+                    self.logger.error(f"rpc {name} failed: {exc}",
+                                      request_id=trace_id, rpc=name)
+                return self._err(_rpc.Code.INTERNAL,
+                                 "internal server error",
+                                 trace_id=trace_id, traceparent=traceparent)
+            headers = {"Content-Type": "application/json",
+                       "X-Request-Id": trace_id, "traceparent": traceparent}
+            if isinstance(result, dict) and result.get("__pyweb_stream__"):
+                return self._stream_response(result["chunks"], headers)
+            from pyweb.ssr import to_jsonable
+            try:
+                payload = json.dumps({"result": to_jsonable(result)})
+            except TypeError as exc:
+                if self.logger is not None:
+                    self.logger.error(f"rpc {name} returned unserializable value: {exc}",
+                                      request_id=trace_id, rpc=name)
+                return self._err(_rpc.Code.INTERNAL, "internal server error",
+                                 trace_id=trace_id, traceparent=traceparent)
+            return Response(200, payload, headers)
+        finally:
+            if span is not None and self.tracer is not None:
+                try:
+                    self.tracer.finish(span)
+                except Exception:
+                    pass
+
+    def _call_with_timeout(self, fn, clean):
+        """Run ``fn`` but stop waiting after ``rpc_timeout`` seconds.
+
+        Python cannot kill a thread, so a timed-out call keeps running in
+        the background pool; the client gets ``timeout`` immediately.
+        """
+        import concurrent.futures as _fut
+        import contextvars
+        ctx = contextvars.copy_context()
+        fut = _rpc_pool().submit(ctx.run, fn, **clean)
+        try:
+            return fut.result(timeout=self.rpc_timeout)
+        except _fut.TimeoutError as exc:
+            raise TimeoutError() from exc
+
+    def _stream_response(self, chunks, headers):
+        """NDJSON stream: one {"chunk": ...} object per line."""
+        headers = dict(headers)
+        headers["Content-Type"] = "application/x-ndjson"
+        lines = "".join(json.dumps({"chunk": c}) + "\n" for c in chunks)
+        return Response(200, lines, headers)
+
+    def handle(self, req: Request):
+        """Dispatch one request inside a :mod:`pyweb.context` request scope."""
+        from pyweb import context as _ctx
+        rc = _ctx.RequestContext(req, auth_secret=self.auth_secret,
+                                 secure_cookies=self.secure_cookies)
+        token = _ctx.activate(rc)
+        try:
+            resp = self._dispatch(req)
+        finally:
+            _ctx.deactivate(token)
+        if resp is not None and rc.set_cookies:
+            existing = resp.headers.get("Set-Cookie")
+            cookies = ([existing] if isinstance(existing, str) else list(existing or [])) + rc.set_cookies
+            resp.headers["Set-Cookie"] = cookies
+        return resp
+
+    def _dispatch(self, req: Request):
+        if req.path.startswith("/__pyweb/rpc/"):
+            if req.method != "POST":
+                return self._err(405, "RPC endpoints accept POST only")
+            return self.handle_rpc(req)
+        if req.path == "/__pyweb/events" or req.path.startswith("/__pyweb/events?"):
+            return self.handle_events(req)
+        if req.path == "/__pyweb/poll" or req.path.startswith("/__pyweb/poll?"):
+            return self.handle_poll(req)
+        path = req.path.split("?")[0]
+        for pat, name in self.routes:
+            m = pat.match(path)
+            if not m:
+                continue
+            if req.method not in ("GET", "HEAD"):
+                return Response(405, "method not allowed", {"Allow": "GET, HEAD",
+                                                            "Content-Type": "text/plain"})
+            if self.app is None:
+                page = self.compiled["pages"][name]
+                return Response(200, page["html"], {"Content-Type": "text/html; charset=utf-8",
+                                                    "X-Request-Id": req.id})
+            return self._render_page(req, name, m.groupdict())
+        return self.error_page(404, req)
+
+    def _render_page(self, req, name, params):
+        from pyweb.context import NotFound, Redirect
+        from urllib.parse import unquote
+        try:
+            result = self.app.render(name, {k: unquote(v) for k, v in params.items()})
+        except NotFound:
+            return self.error_page(404, req)
+        except _rpc_error() as exc:
+            status = {"not_found": 404, "forbidden": 403, "unauthenticated": 401}.get(exc.code)
+            if status is None:
+                raise
+            return self.error_page(status, req, message=str(exc))
+        except Exception as exc:  # noqa: BLE001
+            import traceback
+            if self.logger is not None:
+                self.logger.error(f"page {name} failed: {exc}", request_id=req.id, page=name)
+            if self.debug:
+                return self.error_page(500, req, title=f"{type(exc).__name__} in {name}()",
+                                       message=traceback.format_exc())
+            return self.error_page(500, req)
+        if isinstance(result, Redirect):
+            return Response(result.status, "", {"Location": result.url, "X-Request-Id": req.id})
+        return Response(200, result, {"Content-Type": "text/html; charset=utf-8",
+                                      "X-Request-Id": req.id,
+                                      "Cache-Control": "no-store"})
+
+    def error_page(self, status, req=None, *, title=None, message=None):
+        """Branded HTML error shell. Apps override via ``error_pages`` on
+        the compiled dict (``{404: html, 500: html}``) or ``register_error``.
+
+        Overrides may use ``{{path}}`` and ``{{request_id}}`` placeholders.
+        """
+        overrides = (self.compiled.get("error_pages") or {})
+        template = overrides.get(status)
+        request_id = getattr(req, "id", "") if req is not None else ""
+        path = getattr(req, "path", "") if req is not None else ""
+        if template is not None:
+            body = template.replace("{{path}}", _html.escape(path)).replace(
+                "{{request_id}}", _html.escape(request_id))
+            return Response(status, body,
+                            {"Content-Type": "text/html",
+                             "X-Request-Id": request_id})
+        default_title = {404: "Page not found", 500: "Something went wrong"}
+        heading = _html.escape(title or default_title.get(status, f"Error {status}"))
+        hint = _html.escape(message or ("The page you're looking for doesn't exist. "
+                                        if status == 404 else
+                                        "Please try again; the error has been logged. "))
+        body = (
+            "<!doctype html><html lang=en><meta charset=utf-8>"
+            "<meta name=viewport content='width=device-width,initial-scale=1'>"
+            f"<title>{status} {heading}</title>"
+            "<body style='font-family:system-ui,sans-serif;max-width:640px;"
+            "margin:10vh auto;padding:0 20px;color:#111'>"
+            f"<h1>{status} — {heading}</h1>"
+            + (f"<pre style='white-space:pre-wrap;background:#f6f6f6;padding:12px;font-size:13px'>{hint}</pre>"
+               if message and "\n" in (message or "") else f"<p>{hint}</p>")
+            + (f"<p><a href='/'>Back home</a> · "
+                f"<code>{_html.escape(path)}</code></p>" if status == 404 else "")
+            + (f"<p style='color:#666;font-size:13px'>request id: "
+                f"<code>{_html.escape(request_id)}</code></p>" if request_id else "")
+            + "</body></html>")
+        return Response(status, body, {"Content-Type": "text/html",
+                                       "X-Request-Id": request_id})
+
+    def register_error(self, status, html_template):
+        """Register a custom error shell, e.g. ``register_error(404, ...)``."""
+        pages = self.compiled.setdefault("error_pages", {})
+        pages[status] = html_template
+
+    def handle_events(self, req: Request):
+        """SSE stream: GET /__pyweb/events?channel=NAME replays missed frames
+        (via Last-Event-ID) then emits a live snapshot. Real servers hold the
+        connection open; this runtime returns buffered frames so tests and
+        simple deployments work without streaming infrastructure."""
+        from urllib.parse import urlparse, parse_qs
+        from pyweb import realtime as _rt
+        qs = parse_qs(urlparse(req.path).query)
+        channel_name = (qs.get("channel") or [""])[0]
+        if not channel_name:
+            return Response(400, json.dumps({"error": "missing ?channel="}),
+                            {"Content-Type": "application/json"})
+        last_id = int(req.headers.get("Last-Event-ID", "0") or 0)
+        bus = getattr(self, "bus", None) or _rt._default_bus
+        frames = "".join(
+            _rt.sse_format(seq, channel_name, msg)
+            for seq, msg in bus.since(channel_name, last_id))
+        return Response(200, frames, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            "X-Channel": channel_name,
+            "X-Last-Id": str(bus._seq),
+        })
+
+    def handle_poll(self, req: Request):
+        """Polling fallback: GET /__pyweb/poll?channel=NAME&since=ID."""
+        from urllib.parse import urlparse, parse_qs
+        from pyweb import realtime as _rt
+        qs = parse_qs(urlparse(req.path).query)
+        channel_name = (qs.get("channel") or [""])[0]
+        if not channel_name:
+            return Response(400, json.dumps({"error": "missing ?channel="}),
+                            {"Content-Type": "application/json"})
+        try:
+            since = int((qs.get("since") or ["0"])[0])
+        except ValueError:
+            since = 0
+        bus = getattr(self, "bus", None) or _rt._default_bus
+        messages = [{"id": seq, "channel": channel_name, "data": msg}
+                    for seq, msg in bus.since(channel_name, since)]
+        return Response(200, json.dumps({"messages": messages, "last_id": bus._seq}),
+                        {"Content-Type": "application/json"})

pyweb/security.py

@@ -0,0 +1,162 @@
+"""Security: HTML escaping, CSRF, taint checks, secret-flow analysis,
+path traversal, redirects, error sanitizing, app scanner."""
+
+from __future__ import annotations
+
+import ast
+import html as _html
+import os
+import re
+import traceback
+import urllib.parse
+
+SECRET_RE = re.compile(r"(SECRET|PASSWORD|API_KEY|TOKEN|PRIVATE)", re.I)
+DANGER_SQL = re.compile(r"f[\"'].*(SELECT|INSERT|UPDATE|DELETE)", re.I)
+DANGER_CMD = re.compile(r"(os\.system|subprocess\.(call|run|Popen)|eval\(|exec\()")
+DANGER_PATH = re.compile(r"open\(\s*[A-Za-z_][\w.]*\s*[,)]")
+
+STATIC_DOC = (
+    "Static serving MUST confine reads to the static root. "
+    "Use safe_join(root, user_path): on PathTraversalError respond "
+    "403/404 without revealing the filesystem layout or tracebacks."
+)
+
+_CONCAT_RE = re.compile(r"['\"]\s*\+\s*[a-zA-Z_]")
+_MUTATING = {"POST", "PUT", "PATCH", "DELETE"}
+
+
+class SecurityError(Exception):
+    """Base class for security rejections."""
+
+
+class PathTraversalError(SecurityError):
+    """Raised when a user path escapes the static root."""
+
+
+def escape(text):
+    return _html.escape(str(text))
+
+
+def escape_html(text):
+    return _html.escape(str(text), quote=True)
+
+
+def escape_attr(value):
+    return _html.escape(str(value), quote=True)
+
+
+def ssr(template, **context):
+    """Render ``{{ name }}`` placeholders with ALL values escaped."""
+    out = template
+    for key, value in context.items():
+        out = out.replace("{{ " + key + " }}", escape_html(value))
+        out = out.replace("{{" + key + "}}", escape_html(value))
+    return out
+
+
+def safe_join(root, user_path):
+    """Join ``user_path`` onto ``root``; reject escapes with PathTraversalError."""
+    root_abs = os.path.abspath(root)
+    joined = os.path.abspath(os.path.join(root_abs, user_path))
+    if joined != root_abs and not joined.startswith(root_abs + os.sep):
+        raise PathTraversalError(f"path escapes static root: {user_path!r}")
+    return joined
+
+
+def is_safe_redirect(target):
+    """Allow only relative same-origin paths (no scheme, no //host)."""
+    if not target or not target.startswith("/") or target.startswith("//"):
+        return False
+    if "\\" in target:
+        return False
+    parsed = urllib.parse.urlparse(target)
+    return not parsed.scheme and not parsed.netloc
+
+
+def safe_next(next_param, default="/"):
+    if next_param and is_safe_redirect(next_param):
+        return next_param
+    return default
+
+
+def safe_error(exc):
+    """Render a generic error page that never leaks tracebacks or secrets."""
+    _ = traceback.format_exception(exc)
+    return ("<html><body><h1>Something went wrong</h1>"
+            "<p>Please try again later.</p></body></html>")
+
+
+def _handler_source(route):
+    handler = route.get("handler")
+    if handler is not None and hasattr(handler, "__source__"):
+        return handler.__source__
+    return route.get("handler_source", "")
+
+
+def scan(app):
+    """Scan an app descriptor for secret-leak / xss-risk /
+    missing-auth-on-mutating-rpc findings."""
+    findings = []
+    for route in app.get("routes", []):
+        path = route.get("path", "?")
+        src = _handler_source(route)
+        lowered = src.lower()
+        if ("os.environ" in src and any(
+                k in lowered for k in ("secret", "password", "token",
+                                       "api_key", "apikey", "credential"))):
+            findings.append({
+                "kind": "secret-leak",
+                "path": path,
+                "detail": "handler reads a secret from the environment; "
+                          "ensure it never reaches client bundles/logs",
+            })
+        if ("+" in src and "<div" in src and _CONCAT_RE.search(src)
+                and "escape" not in lowered):
+            findings.append({
+                "kind": "xss-risk",
+                "path": path,
+                "detail": "handler concatenates HTML without escaping; "
+                          "use security.ssr/escape_html",
+            })
+        methods = {m.upper() for m in route.get("methods", ["GET"])}
+        if methods & _MUTATING and not route.get("auth", False):
+            findings.append({
+                "kind": "missing-auth-on-mutating-rpc",
+                "path": path,
+                "detail": f"mutating methods {sorted(methods & _MUTATING)} "
+                          "without auth guard",
+            })
+    return findings
+
+
+def check_source(source, filename="<pyweb>"):
+    """Return a list of {'kind', 'line', 'message'} findings."""
+    findings = []
+    for i, line in enumerate(source.splitlines(), start=1):
+        if DANGER_SQL.search(line):
+            findings.append({"kind": "sql-injection", "line": i,
+                             "message": "possible SQL string interpolation; use parameterized queries"})
+        if DANGER_CMD.search(line):
+            findings.append({"kind": "command-injection", "line": i,
+                             "message": "dangerous call (os.system/subprocess/eval/exec)"})
+    try:
+        tree = ast.parse(source, filename=filename)
+    except SyntaxError:
+        return findings
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            decos = [ast.unparse(d) if hasattr(ast, "unparse") else "" for d in node.decorator_list]
+            if any("browser" in d for d in decos):
+                for sub in ast.walk(node):
+                    if isinstance(sub, ast.Name) and SECRET_RE.search(sub.id):
+                        findings.append({"kind": "secret-leak", "line": getattr(sub, "lineno", 0),
+                                         "message": f"server secret {sub.id!r} referenced from @browser code"})
+    return findings
+
+
+def assert_browser_safe(source, filename="<pyweb>"):
+    leaks = [f for f in check_source(source, filename) if f["kind"] == "secret-leak"]
+    if leaks:
+        f = leaks[0]
+        raise ValueError(f"ERROR: server secret referenced from browser-executed code ({filename}:{f['line']})")
+    return True