medfunnels 1.0.0__tar.gz

medfunnels-1.0.0/LICENSE

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

medfunnels-1.0.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: medfunnels
+Version: 1.0.0
+Summary: Run medFunnels patient questionnaires on your own platform: fetch, verify, host and validate them server-side.
+Author: medFunnels
+License-Expression: MIT
+Project-URL: Homepage, https://www.medfunnels.app
+Keywords: medfunnels,telehealth,questionnaire,intake,hipaa
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: verify
+Requires-Dist: cryptography>=42; extra == "verify"
+Dynamic: license-file
+
+# medfunnels
+
+Run [medFunnels](https://www.medfunnels.app) patient questionnaires on your own platform from Python: an
+Integration API client, release verification, the sandboxed frame, and authoritative answer validation.
+**Patient data never goes to medFunnels.**
+
+```bash
+pip install "medfunnels[verify]"
+```
+
+```python
+from medfunnels.client import MedFunnelsClient
+from medfunnels.contract import validate_response
+from medfunnels.frame import build_frame
+from medfunnels.verify import verify_release
+
+client = MedFunnelsClient("https://www.medfunnels.app", CLIENT_ID, CLIENT_SECRET)  # server-side only
+page = client.release_updates(cursor=cursor)
+release_id = page["updates"][0]["id"]
+envelope = client.get_manifest(release_id)
+artifacts = {a["name"]: client.download_artifact(release_id, a["name"]) for a in envelope["manifest"]["artifacts"]}
+release = verify_release(envelope, artifacts, trusted_keys=PINNED_KEYS, supported_kinds=SUPPORTED_KINDS,
+                         expected_organization_id=ORGANIZATION_ID, expected_origin="https://intake.example.com")
+
+html, headers = build_frame(release.bundle, title=release.manifest["questionnaire"]["name"])  # serve both unchanged
+answers = validate_response(release.definition, submitted, questionnaire_id=release.questionnaire_id, release_id=release.release_id)
+```
+
+No required dependencies; the `verify` extra adds `cryptography` for signature checks. Python 3.10 or later.
+The full guide, with your workspace's values filled in, is in medFunnels under **Integrations → Developer guide**.
+Using Next.js? See [`@medfunnels/next`](https://www.npmjs.com/package/@medfunnels/next).

medfunnels-1.0.0/README.md

@@ -0,0 +1,31 @@
+# medfunnels
+
+Run [medFunnels](https://www.medfunnels.app) patient questionnaires on your own platform from Python: an
+Integration API client, release verification, the sandboxed frame, and authoritative answer validation.
+**Patient data never goes to medFunnels.**
+
+```bash
+pip install "medfunnels[verify]"
+```
+
+```python
+from medfunnels.client import MedFunnelsClient
+from medfunnels.contract import validate_response
+from medfunnels.frame import build_frame
+from medfunnels.verify import verify_release
+
+client = MedFunnelsClient("https://www.medfunnels.app", CLIENT_ID, CLIENT_SECRET)  # server-side only
+page = client.release_updates(cursor=cursor)
+release_id = page["updates"][0]["id"]
+envelope = client.get_manifest(release_id)
+artifacts = {a["name"]: client.download_artifact(release_id, a["name"]) for a in envelope["manifest"]["artifacts"]}
+release = verify_release(envelope, artifacts, trusted_keys=PINNED_KEYS, supported_kinds=SUPPORTED_KINDS,
+                         expected_organization_id=ORGANIZATION_ID, expected_origin="https://intake.example.com")
+
+html, headers = build_frame(release.bundle, title=release.manifest["questionnaire"]["name"])  # serve both unchanged
+answers = validate_response(release.definition, submitted, questionnaire_id=release.questionnaire_id, release_id=release.release_id)
+```
+
+No required dependencies; the `verify` extra adds `cryptography` for signature checks. Python 3.10 or later.
+The full guide, with your workspace's values filled in, is in medFunnels under **Integrations → Developer guide**.
+Using Next.js? See [`@medfunnels/next`](https://www.npmjs.com/package/@medfunnels/next).

medfunnels-1.0.0/medfunnels/__init__.py

@@ -0,0 +1,28 @@
+"""medFunnels SDK: fetch, verify, host, and validate published questionnaires on your own platform.
+
+Everything here runs on the consumer's own infrastructure. Nothing in this package sends
+patient data to medFunnels.
+"""
+from medfunnels.canonical import canonical_json, csp_hash, sha256_hex
+from medfunnels.client import IntegrationError, MedFunnelsClient
+from medfunnels.contract import ANSWER_CONTRACT, ContractError, NormalizedAnswer, evaluate_condition, validate_response
+from medfunnels.frame import FRAME_SANDBOX, build_frame
+from medfunnels.verify import VerificationError, VerifiedRelease, verify_release
+
+__all__ = [
+    "ANSWER_CONTRACT",
+    "ContractError",
+    "FRAME_SANDBOX",
+    "IntegrationError",
+    "MedFunnelsClient",
+    "NormalizedAnswer",
+    "VerificationError",
+    "VerifiedRelease",
+    "build_frame",
+    "canonical_json",
+    "csp_hash",
+    "evaluate_condition",
+    "sha256_hex",
+    "validate_response",
+    "verify_release",
+]

medfunnels-1.0.0/medfunnels/canonical.py

@@ -0,0 +1,28 @@
+"""Canonical JSON used for manifest signing. Signer and verifier must share this exact function."""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from typing import Any
+
+
+def canonical_json(value: Any) -> bytes:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False).encode("utf-8")
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def csp_hash(script: bytes) -> str:
+    """Value for a CSP `script-src 'sha256-…'` source matching an inline script with exactly these bytes."""
+    return "sha256-" + base64.b64encode(hashlib.sha256(script).digest()).decode("ascii")
+
+
+def b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def b64url_decode(value: str) -> bytes:
+    return base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))

medfunnels-1.0.0/medfunnels/client.py

@@ -0,0 +1,123 @@
+"""Server-side client for the medicalforms.ai Integration API v1 (stdlib only).
+
+Runs on the consumer's backend. The client secret never leaves the server. The client
+exposes read operations only; there is deliberately no method that sends patient data.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+USER_AGENT = "medfunnels-python/1.0"
+
+
+class IntegrationError(RuntimeError):
+    """`code` is stable for diagnostics UIs: network | auth | plan_required | forbidden | not_found | rate_limited | server | protocol."""
+
+    def __init__(self, code: str, message: str, *, status: int = 0, request_id: str = ""):
+        self.code = code
+        self.status = status
+        self.request_id = request_id
+        super().__init__(message)
+
+
+@dataclass
+class _Token:
+    value: str
+    expires_at: float
+    scope: str
+
+
+class MedFunnelsClient:
+    def __init__(self, base_url: str, client_id: str, client_secret: str, *, timeout: float = 15.0):
+        parsed = urllib.parse.urlparse(base_url)
+        if parsed.scheme != "https" and parsed.hostname not in {"localhost", "127.0.0.1"}:
+            raise ValueError("medicalforms.ai API endpoint must use https.")
+        self.base_url = base_url.rstrip("/")
+        self.client_id = client_id
+        self._client_secret = client_secret
+        self.timeout = timeout
+        self._token: _Token | None = None
+
+    def __repr__(self) -> str:  # never render the secret in logs or tracebacks
+        return f"MedFunnelsClient(base_url={self.base_url!r}, client_id={self.client_id!r})"
+
+    # -- auth ---------------------------------------------------------------
+    def _access_token(self) -> str:
+        if self._token and self._token.expires_at - 30 > time.time():
+            return self._token.value
+        basic = base64.b64encode(f"{self.client_id}:{self._client_secret}".encode()).decode()
+        body = urllib.parse.urlencode({"grant_type": "client_credentials"}).encode()
+        payload = self._send("POST", "/api/v1/oauth/token", body=body, headers={
+            "Authorization": f"Basic {basic}",
+            "Content-Type": "application/x-www-form-urlencoded",
+        })
+        data = json.loads(payload)
+        self._token = _Token(data["access_token"], time.time() + int(data.get("expires_in", 300)), data.get("scope", ""))
+        return self._token.value
+
+    # -- transport ----------------------------------------------------------
+    def _send(self, method: str, path: str, *, body: bytes | None = None, headers: dict[str, str] | None = None) -> bytes:
+        request = urllib.request.Request(self.base_url + path, data=body, method=method, headers={"User-Agent": USER_AGENT, "Accept": "application/json", **(headers or {})})
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                return response.read()
+        except urllib.error.HTTPError as exc:
+            request_id = exc.headers.get("X-Request-Id", "") if exc.headers else ""
+            detail = _error_detail(exc)
+            code = {400: "protocol", 401: "auth", 402: "plan_required", 403: "forbidden", 404: "not_found", 429: "rate_limited"}.get(exc.code, "server" if exc.code >= 500 else "protocol")
+            raise IntegrationError(code, detail or f"HTTP {exc.code}", status=exc.code, request_id=request_id) from None
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            raise IntegrationError("network", f"Could not reach medFunnels: {getattr(exc, 'reason', exc)}") from None
+
+    def _get(self, path: str, params: dict[str, Any] | None = None, *, accept: str = "application/json") -> bytes:
+        query = f"?{urllib.parse.urlencode({k: v for k, v in (params or {}).items() if v not in (None, '')})}" if params else ""
+        try:
+            return self._send("GET", path + query, headers={"Authorization": f"Bearer {self._access_token()}", "Accept": accept})
+        except IntegrationError as exc:
+            if exc.code == "auth" and self._token is not None:
+                self._token = None  # token revoked or expired early: retry once with a fresh token
+                return self._send("GET", path + query, headers={"Authorization": f"Bearer {self._access_token()}", "Accept": accept})
+            raise
+
+    def _get_json(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        return json.loads(self._get(path, params))
+
+    # -- API ----------------------------------------------------------------
+    def test_connection(self) -> dict[str, Any]:
+        return self._get_json("/api/v1/integration/connection")
+
+    def list_questionnaires(self, *, query: str = "", cursor: str = "", limit: int = 50) -> dict[str, Any]:
+        return self._get_json("/api/v1/questionnaires", {"q": query, "cursor": cursor, "limit": limit})
+
+    def get_questionnaire(self, questionnaire_id: str) -> dict[str, Any]:
+        return self._get_json(f"/api/v1/questionnaires/{urllib.parse.quote(questionnaire_id)}")
+
+    def list_releases(self, questionnaire_id: str, *, after_version: int = 0) -> dict[str, Any]:
+        return self._get_json(f"/api/v1/questionnaires/{urllib.parse.quote(questionnaire_id)}/releases", {"after_version": after_version or None})
+
+    def release_updates(self, *, cursor: str = "") -> dict[str, Any]:
+        return self._get_json("/api/v1/releases/updates", {"cursor": cursor})
+
+    def get_manifest(self, release_id: str) -> dict[str, Any]:
+        return self._get_json(f"/api/v1/releases/{urllib.parse.quote(release_id)}/manifest")
+
+    def download_artifact(self, release_id: str, name: str) -> bytes:
+        return self._get(f"/api/v1/releases/{urllib.parse.quote(release_id)}/artifacts/{urllib.parse.quote(name)}", accept="*/*")
+
+
+def _error_detail(exc: urllib.error.HTTPError) -> str:
+    try:
+        data = json.loads(exc.read() or b"{}")
+    except (ValueError, OSError):
+        return ""
+    error = data.get("error")
+    if isinstance(error, dict):
+        return str(error.get("message") or "")
+    return str(data.get("detail") or data.get("error_description") or "")

medfunnels-1.0.0/medfunnels/contract.py

@@ -0,0 +1,236 @@
+"""Server-side answer contract (`medicalforms.answers/v1`).
+
+Consumers call `validate_response` on their own backend with the definition they
+synchronized and verified. The browser runtime's validation is a convenience only;
+this module is the authority. Python/JS parity is covered by tests/fixtures/conditions.json.
+"""
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+ANSWER_CONTRACT = "medicalforms.answers/v1"
+CHOICE_KINDS = {"single_choice", "multi_choice"}
+ANSWERABLE_KINDS = {"text", "textarea", "single_choice", "multi_choice", "boolean", "number", "date"}
+DATE_PATTERN = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+DEFAULT_MAX_TEXT = 2000
+
+
+class ContractError(ValueError):
+    """Raised when a response cannot be accepted. `errors` maps question keys (or "_") to messages."""
+
+    def __init__(self, errors: dict[str, str]):
+        self.errors = errors
+        super().__init__("; ".join(f"{key}: {message}" for key, message in errors.items()))
+
+
+@dataclass(frozen=True)
+class NormalizedAnswer:
+    question_key: str
+    kind: str
+    value: Any
+    display_value: str
+    question: dict[str, Any] = field(repr=False)
+
+
+def is_answered(value: Any) -> bool:
+    if value is None:
+        return False
+    if isinstance(value, bool):
+        return True
+    if isinstance(value, str):
+        return value.strip() != ""
+    if isinstance(value, list):
+        return len(value) > 0
+    if isinstance(value, (int, float)):
+        return math.isfinite(value)
+    return False
+
+
+def evaluate_condition(condition: Any, answers: dict[str, Any]) -> bool:
+    if not isinstance(condition, dict):
+        return True
+    op = condition.get("op")
+    if op == "all":
+        return all(evaluate_condition(item, answers) for item in condition.get("conditions") or [])
+    if op == "any":
+        return any(evaluate_condition(item, answers) for item in condition.get("conditions") or [])
+    if op == "not":
+        return not evaluate_condition(condition.get("condition"), answers)
+    value = answers.get(condition.get("question"))
+    if op == "answered":
+        return is_answered(value)
+    if not is_answered(value):
+        return False
+    target = condition.get("value")
+    if op == "equals":
+        return _same(value, target)
+    if op == "not_equals":
+        return not _same(value, target)
+    if op == "in":
+        values = condition.get("values")
+        return isinstance(values, list) and any(_same(value, item) for item in values)
+    if op == "includes":
+        return isinstance(value, list) and any(_same(item, target) for item in value)
+    if not _is_number(value) or not _is_number(target):
+        return False
+    return {"gt": value > target, "gte": value >= target, "lt": value < target, "lte": value <= target}.get(op, False)
+
+
+def _is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)
+
+
+def _same(left: Any, right: Any) -> bool:
+    # Mirror JS strict equality: booleans never equal numbers.
+    if isinstance(left, bool) or isinstance(right, bool):
+        return isinstance(left, bool) and isinstance(right, bool) and left == right
+    return type(left) is type(right) and left == right or (_is_number(left) and _is_number(right) and left == right)
+
+
+def prune_hidden(definition: dict[str, Any], answers: dict[str, Any]) -> dict[str, Any]:
+    current = dict(answers)
+    for _ in range(10):
+        nxt: dict[str, Any] = {}
+        for page in definition["pages"]:
+            page_visible = evaluate_condition(page.get("visibleWhen"), current)
+            for question in page["questions"]:
+                if page_visible and evaluate_condition(question.get("visibleWhen"), current) and question["key"] in current:
+                    nxt[question["key"]] = current[question["key"]]
+        if len(nxt) == len(current):
+            return nxt
+        current = nxt
+    return current
+
+
+def visible_questions(definition: dict[str, Any], answers: dict[str, Any]) -> list[dict[str, Any]]:
+    pruned = prune_hidden(definition, answers)
+    return [
+        question
+        for page in definition["pages"]
+        if evaluate_condition(page.get("visibleWhen"), pruned)
+        for question in page["questions"]
+        if evaluate_condition(question.get("visibleWhen"), pruned)
+    ]
+
+
+def answer_error(question: dict[str, Any], value: Any) -> str:
+    kind = question["kind"]
+    if kind in ("statement", "end"):
+        return ""
+    if not is_answered(value):
+        return "This question is required." if question.get("required", True) else ""
+    rules = question.get("validation") or {}
+    if kind in {"text", "textarea"}:
+        if not isinstance(value, str):
+            return "Enter text."
+        if len(value) > int(rules.get("maxLength") or DEFAULT_MAX_TEXT):
+            return "Answer is too long."
+    elif kind == "number":
+        if not _is_number(value):
+            return "Enter a number."
+        if _is_number(rules.get("min")) and value < rules["min"]:
+            return f"Enter {rules['min']} or more."
+        if _is_number(rules.get("max")) and value > rules["max"]:
+            return f"Enter {rules['max']} or less."
+    elif kind == "date":
+        if not isinstance(value, str) or not DATE_PATTERN.match(value):
+            return "Enter a date."
+        if rules.get("minDate") and value < rules["minDate"]:
+            return "Enter a later date."
+        if rules.get("maxDate") and value > rules["maxDate"]:
+            return "Enter an earlier date."
+    elif kind == "boolean":
+        if not isinstance(value, bool):
+            return "Choose yes or no."
+    elif kind in CHOICE_KINDS:
+        keys = [option["key"] for option in question.get("options") or []]
+        if kind == "single_choice" and value not in keys:
+            return "Choose an option."
+        if kind == "multi_choice" and (not isinstance(value, list) or any(item not in keys for item in value) or len(set(value)) != len(value)):
+            return "Choose from the options."
+    return ""
+
+
+def display_value(question: dict[str, Any], value: Any) -> str:
+    if not is_answered(value):
+        return ""
+    if question["kind"] == "boolean":
+        return "Yes" if value else "No"
+    if question["kind"] in CHOICE_KINDS:
+        labels = {option["key"]: option["label"] for option in question.get("options") or []}
+        keys = value if isinstance(value, list) else [value]
+        return ", ".join(labels.get(key, str(key)) for key in keys)
+    if isinstance(value, float) and value.is_integer():
+        return str(int(value))
+    return str(value)
+
+
+def validate_response(
+    definition: dict[str, Any],
+    response: Any,
+    *,
+    questionnaire_id: str,
+    release_id: str,
+) -> list[NormalizedAnswer]:
+    """Authoritatively validate a browser-submitted response against a verified definition.
+
+    Rejects: wrong contract/release, unknown or duplicate keys, answers to hidden
+    questions, values outside the declared options/ranges, missing required answers, and
+    answers that reach a stop screen (kind "end").
+    Returns answers in definition order, with display text for downstream reviewers.
+    """
+    if not isinstance(response, dict):
+        raise ContractError({"_": "Response must be an object."})
+    if response.get("contract") != ANSWER_CONTRACT:
+        raise ContractError({"_": "Unsupported answer contract."})
+    if response.get("questionnaireId") != questionnaire_id or response.get("releaseId") != release_id:
+        raise ContractError({"_": "Response does not belong to the active questionnaire release."})
+    items = response.get("answers")
+    if not isinstance(items, list) or len(items) > 500:
+        raise ContractError({"_": "Answers must be a list."})
+
+    questions = {question["key"]: question for page in definition["pages"] for question in page["questions"]}
+    submitted: dict[str, Any] = {}
+    errors: dict[str, str] = {}
+    for item in items:
+        if not isinstance(item, dict) or not isinstance(item.get("questionKey"), str):
+            raise ContractError({"_": "Each answer needs a questionKey."})
+        key = item["questionKey"]
+        question = questions.get(key)
+        if question is None or question["kind"] not in ANSWERABLE_KINDS:
+            errors[key] = "Unknown question."
+            continue
+        if key in submitted:
+            errors[key] = "Answered more than once."
+            continue
+        if item.get("kind") != question["kind"]:
+            errors[key] = "Answer kind does not match the question."
+            continue
+        submitted[key] = item.get("value")
+    if errors:
+        raise ContractError(errors)
+
+    visible = visible_questions(definition, submitted)
+    # A visible stop screen means the patient was told they can't continue; never accept such a response.
+    stopped = [question["key"] for question in visible if question["kind"] == "end"]
+    if stopped:
+        raise ContractError({stopped[0]: "These answers end the questionnaire at a stop screen, so it cannot be submitted."})
+    visible_keys = {question["key"] for question in visible}
+    for key in submitted:
+        if key not in visible_keys:
+            errors[key] = "This question was not shown and cannot be answered."
+    for question in visible:
+        message = answer_error(question, submitted.get(question["key"]))
+        if message:
+            errors[question["key"]] = message
+    if errors:
+        raise ContractError(errors)
+
+    return [
+        NormalizedAnswer(question["key"], question["kind"], submitted[question["key"]], display_value(question, submitted[question["key"]]), question)
+        for question in visible
+        if question["kind"] in ANSWERABLE_KINDS and is_answered(submitted.get(question["key"]))
+    ]

medfunnels-1.0.0/medfunnels/frame.py

@@ -0,0 +1,71 @@
+"""Customer-hosted sandbox frame for a verified questionnaire bundle.
+
+The consumer serves this HTML from ITS OWN origin. Isolation comes from three layers:
+
+1. The host page embeds it with `<iframe sandbox="allow-scripts allow-forms">` (never
+   `allow-same-origin`), giving the document an opaque origin: no access to the host's
+   cookies, storage, DOM, or authenticated APIs.
+2. The CSP `sandbox` directive re-applies the same sandbox even if the frame URL is opened
+   directly as a top-level page.
+3. `script-src` allows only the exact verified bundle bytes (hash source), and
+   `connect-src`/`img-src`/`font-src` are `'none'`, so the runtime has no network channel.
+   Answers leave only by postMessage to the host page.
+"""
+from __future__ import annotations
+
+import html
+
+from medfunnels.canonical import csp_hash
+
+FRAME_SANDBOX = "allow-scripts allow-forms"
+
+
+def frame_csp(script_hash: str, *, frame_ancestors: str = "'self'") -> str:
+    return "; ".join(
+        [
+            "default-src 'none'",
+            f"script-src '{script_hash}'",
+            "style-src 'unsafe-inline'",
+            "img-src 'none'",
+            "font-src 'none'",
+            "connect-src 'none'",
+            "media-src 'none'",
+            "object-src 'none'",
+            "child-src 'none'",
+            "worker-src 'none'",
+            "manifest-src 'none'",
+            "form-action 'none'",
+            "base-uri 'none'",
+            f"frame-ancestors {frame_ancestors}",
+            f"sandbox {FRAME_SANDBOX}",
+        ]
+    )
+
+
+def frame_headers(script_hash: str, *, frame_ancestors: str = "'self'") -> dict[str, str]:
+    return {
+        "Content-Type": "text/html; charset=utf-8",
+        "Content-Security-Policy": frame_csp(script_hash, frame_ancestors=frame_ancestors),
+        "X-Content-Type-Options": "nosniff",
+        "Referrer-Policy": "no-referrer",
+        "Cross-Origin-Resource-Policy": "same-origin",
+        "Permissions-Policy": "camera=(), microphone=(), geolocation=(), payment=(), usb=(), clipboard-read=(), clipboard-write=()",
+        "Cache-Control": "private, max-age=300",
+    }
+
+
+def build_frame_html(bundle: bytes, *, title: str, lang: str = "en") -> bytes:
+    if b"</script" in bundle.lower():
+        raise ValueError("Bundle contains a closing script tag and cannot be inlined.")
+    head = (
+        "<!doctype html>"
+        f'<html lang="{html.escape(lang[:20], quote=True)}"><head><meta charset="utf-8">'
+        '<meta name="viewport" content="width=device-width, initial-scale=1">'
+        f"<title>{html.escape(title[:240])}</title></head><body><script>"
+    ).encode("utf-8")
+    return head + bundle + b"</script></body></html>"
+
+
+def build_frame(bundle: bytes, *, title: str, lang: str = "en", frame_ancestors: str = "'self'") -> tuple[bytes, dict[str, str]]:
+    """Return (html, headers). Serve both exactly; the CSP hash binds the page to these bundle bytes."""
+    return build_frame_html(bundle, title=title, lang=lang), frame_headers(csp_hash(bundle), frame_ancestors=frame_ancestors)

medfunnels-1.0.0/medfunnels/verify.py

@@ -0,0 +1,120 @@
+"""Release verification: authenticity (Ed25519 signature), integrity (SHA-256), compatibility.
+
+Requires the `cryptography` package for signature verification. Consumers must pin the
+medicalforms.ai signing public keys in their own configuration (not fetch-and-trust).
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from medfunnels.canonical import b64url_decode, canonical_json, csp_hash, sha256_hex
+from medfunnels.contract import ANSWER_CONTRACT
+
+SUPPORTED_MANIFEST_VERSIONS = {1}
+SUPPORTED_RUNTIME_MAJORS = {1}
+BUNDLE_ARTIFACT = "questionnaire.js"
+DEFINITION_ARTIFACT = "definition.json"
+
+
+class VerificationError(ValueError):
+    def __init__(self, code: str, message: str):
+        self.code = code
+        super().__init__(message)
+
+
+@dataclass(frozen=True)
+class VerifiedRelease:
+    manifest: dict[str, Any]
+    definition: dict[str, Any]
+    bundle: bytes
+    bundle_sha256: str
+    bundle_csp_hash: str
+
+    @property
+    def questionnaire_id(self) -> str:
+        return self.manifest["questionnaire"]["id"]
+
+    @property
+    def release_id(self) -> str:
+        return self.manifest["release"]["id"]
+
+    @property
+    def version(self) -> int:
+        return int(self.manifest["release"]["version"])
+
+
+def verify_signature(envelope: dict[str, Any], trusted_keys: dict[str, str]) -> dict[str, Any]:
+    """Verify a `{manifest, signature}` envelope. `trusted_keys` maps key id → base64url raw Ed25519 public key."""
+    try:
+        from cryptography.exceptions import InvalidSignature
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+    except ImportError as exc:  # pragma: no cover - environment guard
+        raise VerificationError("crypto_unavailable", "Install `cryptography` to verify release signatures.") from exc
+
+    manifest = envelope.get("manifest")
+    signature = envelope.get("signature") or {}
+    if not isinstance(manifest, dict):
+        raise VerificationError("malformed", "Manifest envelope is missing its manifest.")
+    if signature.get("alg") != "Ed25519":
+        raise VerificationError("bad_signature", "Unsupported signature algorithm.")
+    key = trusted_keys.get(str(signature.get("keyId") or ""))
+    if not key:
+        raise VerificationError("untrusted_key", f"Signing key {signature.get('keyId')!r} is not trusted by this installation.")
+    try:
+        Ed25519PublicKey.from_public_bytes(b64url_decode(key)).verify(b64url_decode(str(signature.get("value") or "")), canonical_json(manifest))
+    except (InvalidSignature, ValueError) as exc:
+        raise VerificationError("bad_signature", "Release manifest signature is invalid.") from exc
+    return manifest
+
+
+def check_compatibility(manifest: dict[str, Any], *, supported_kinds: set[str]) -> None:
+    if manifest.get("manifestVersion") not in SUPPORTED_MANIFEST_VERSIONS:
+        raise VerificationError("incompatible", "Unsupported manifest version.")
+    compatibility = manifest.get("compatibility") or {}
+    if compatibility.get("answerContract") != ANSWER_CONTRACT:
+        raise VerificationError("incompatible", "Unsupported answer contract.")
+    runtime_version = str((manifest.get("runtime") or {}).get("version") or "0")
+    if int(runtime_version.split(".")[0] or 0) not in SUPPORTED_RUNTIME_MAJORS:
+        raise VerificationError("incompatible", f"Unsupported runtime version {runtime_version}.")
+    if compatibility.get("requiresNetwork") is not False:
+        raise VerificationError("incompatible", "Questionnaire runtime must not require network access.")
+    unsupported = set(compatibility.get("questionKinds") or []) - supported_kinds
+    if unsupported:
+        raise VerificationError("incompatible", f"Unsupported question kinds: {', '.join(sorted(unsupported))}.")
+
+
+def verify_release(
+    envelope: dict[str, Any],
+    artifacts: dict[str, bytes],
+    *,
+    trusted_keys: dict[str, str],
+    supported_kinds: set[str],
+    expected_organization_id: str | None = None,
+    expected_origin: str | None = None,
+) -> VerifiedRelease:
+    """`expected_origin` (e.g. "https://intake.example.com") rejects releases locked to another site."""
+    manifest = verify_signature(envelope, trusted_keys)
+    if expected_organization_id and manifest.get("organizationId") != expected_organization_id:
+        raise VerificationError("wrong_tenant", "Release belongs to a different organization.")
+    allowed = (manifest.get("deployment") or {}).get("allowedOrigins") or []
+    if expected_origin and allowed and expected_origin.rstrip("/") not in allowed:
+        raise VerificationError("wrong_origin", f"Release is locked to {', '.join(allowed)}, not {expected_origin}.")
+    if (manifest.get("release") or {}).get("status") != "published":
+        raise VerificationError("not_published", "Release is not in published status.")
+    check_compatibility(manifest, supported_kinds=supported_kinds)
+
+    declared = {item["name"]: item for item in manifest.get("artifacts") or []}
+    for name in (BUNDLE_ARTIFACT, DEFINITION_ARTIFACT):
+        meta = declared.get(name)
+        data = artifacts.get(name)
+        if meta is None or data is None:
+            raise VerificationError("missing_artifact", f"Release artifact {name} is missing.")
+        if len(data) != int(meta.get("size", -1)) or sha256_hex(data) != meta.get("sha256"):
+            raise VerificationError("digest_mismatch", f"Artifact {name} does not match its signed digest.")
+    bundle = artifacts[BUNDLE_ARTIFACT]
+    if declared[BUNDLE_ARTIFACT].get("cspHash") != csp_hash(bundle):
+        raise VerificationError("digest_mismatch", "Bundle CSP hash does not match.")
+    definition = json.loads(artifacts[DEFINITION_ARTIFACT].decode("utf-8"))
+    return VerifiedRelease(manifest, definition, bundle, sha256_hex(bundle), csp_hash(bundle))

medfunnels-1.0.0/medfunnels.egg-info/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: medfunnels
+Version: 1.0.0
+Summary: Run medFunnels patient questionnaires on your own platform: fetch, verify, host and validate them server-side.
+Author: medFunnels
+License-Expression: MIT
+Project-URL: Homepage, https://www.medfunnels.app
+Keywords: medfunnels,telehealth,questionnaire,intake,hipaa
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: verify
+Requires-Dist: cryptography>=42; extra == "verify"
+Dynamic: license-file
+
+# medfunnels
+
+Run [medFunnels](https://www.medfunnels.app) patient questionnaires on your own platform from Python: an
+Integration API client, release verification, the sandboxed frame, and authoritative answer validation.
+**Patient data never goes to medFunnels.**
+
+```bash
+pip install "medfunnels[verify]"
+```
+
+```python
+from medfunnels.client import MedFunnelsClient
+from medfunnels.contract import validate_response
+from medfunnels.frame import build_frame
+from medfunnels.verify import verify_release
+
+client = MedFunnelsClient("https://www.medfunnels.app", CLIENT_ID, CLIENT_SECRET)  # server-side only
+page = client.release_updates(cursor=cursor)
+release_id = page["updates"][0]["id"]
+envelope = client.get_manifest(release_id)
+artifacts = {a["name"]: client.download_artifact(release_id, a["name"]) for a in envelope["manifest"]["artifacts"]}
+release = verify_release(envelope, artifacts, trusted_keys=PINNED_KEYS, supported_kinds=SUPPORTED_KINDS,
+                         expected_organization_id=ORGANIZATION_ID, expected_origin="https://intake.example.com")
+
+html, headers = build_frame(release.bundle, title=release.manifest["questionnaire"]["name"])  # serve both unchanged
+answers = validate_response(release.definition, submitted, questionnaire_id=release.questionnaire_id, release_id=release.release_id)
+```
+
+No required dependencies; the `verify` extra adds `cryptography` for signature checks. Python 3.10 or later.
+The full guide, with your workspace's values filled in, is in medFunnels under **Integrations → Developer guide**.
+Using Next.js? See [`@medfunnels/next`](https://www.npmjs.com/package/@medfunnels/next).

medfunnels-1.0.0/medfunnels.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+medfunnels/__init__.py
+medfunnels/canonical.py
+medfunnels/client.py
+medfunnels/contract.py
+medfunnels/frame.py
+medfunnels/verify.py
+medfunnels.egg-info/PKG-INFO
+medfunnels.egg-info/SOURCES.txt
+medfunnels.egg-info/dependency_links.txt
+medfunnels.egg-info/requires.txt
+medfunnels.egg-info/top_level.txt

medfunnels-1.0.0/medfunnels.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

medfunnels-1.0.0/medfunnels.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[verify]
+cryptography>=42

medfunnels-1.0.0/medfunnels.egg-info/top_level.txt

@@ -0,0 +1 @@
+medfunnels

medfunnels-1.0.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "medfunnels"
+version = "1.0.0"
+description = "Run medFunnels patient questionnaires on your own platform: fetch, verify, host and validate them server-side."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "medFunnels" }]
+keywords = ["medfunnels", "telehealth", "questionnaire", "intake", "hipaa"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.optional-dependencies]
+verify = ["cryptography>=42"]
+
+[project.urls]
+Homepage = "https://www.medfunnels.app"
+
+[tool.setuptools.packages.find]
+include = ["medfunnels*"]

medfunnels-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+