cmp-consent 0.1.1__py3-none-any.whl

cmp_consent/__init__.py

@@ -0,0 +1,36 @@
+"""cmp-consent — Python SDK for the CMP officer-assisted deferred consent flow.
+
+Server-to-server: raise consent requests, gate PII processing on verify(), and
+validate CMP's signed webhooks. The application API key stays on your backend.
+"""
+
+from __future__ import annotations
+
+from .aio import AsyncCMPClient
+from .client import CMPClient
+from .errors import (
+    CMPError,
+    ConsentDeclined,
+    ConsentExpired,
+    ConsentPending,
+    SignatureError,
+)
+from .models import ConsentRequest, RequestStatus, VerifyResult, WebhookEvent
+from .webhooks import verify_signature
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "CMPClient",
+    "AsyncCMPClient",
+    "ConsentRequest",
+    "RequestStatus",
+    "VerifyResult",
+    "WebhookEvent",
+    "verify_signature",
+    "CMPError",
+    "ConsentPending",
+    "ConsentDeclined",
+    "ConsentExpired",
+    "SignatureError",
+]

cmp_consent/aio.py

@@ -0,0 +1,118 @@
+"""Asynchronous CMP consent client — the awaitable mirror of CMPClient."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Mapping
+
+import httpx
+
+from .client import _envelope_error, _raise_not_allowed
+from .errors import CMPError, SignatureError
+from .models import ConsentRequest, RequestStatus, VerifyResult, WebhookEvent
+from .webhooks import verify_signature
+
+
+class AsyncCMPClient:
+    def __init__(
+        self,
+        api_base: str,
+        api_key: str,
+        *,
+        webhook_secret: str | None = None,
+        timeout: float = 10.0,
+        retries: int = 2,
+    ):
+        self.api_base = api_base.rstrip("/")
+        self.api_key = api_key
+        self.webhook_secret = webhook_secret
+        self._http = httpx.AsyncClient(
+            base_url=self.api_base,
+            timeout=timeout,
+            headers={"X-API-Key": api_key},
+            transport=httpx.AsyncHTTPTransport(retries=retries),
+        )
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncCMPClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    async def _request(self, method: str, path: str, **kw: Any) -> Any:
+        try:
+            resp = await self._http.request(method, path, **kw)
+        except httpx.HTTPError as e:
+            raise CMPError(f"request failed: {e}") from e
+        if resp.status_code >= 400:
+            raise _envelope_error(resp)
+        return resp.json() if resp.content else {}
+
+    async def create_consent_request(
+        self,
+        *,
+        email: str,
+        notice: str,
+        requested_by: str,
+        idempotency_key: str | None = None,
+        link_expire_seconds: int | None = None,
+    ) -> ConsentRequest:
+        """See CMPClient.create_consent_request. One request covers one notice."""
+        body: dict[str, Any] = {
+            "email": email,
+            "notice_key": notice,
+            "requested_by": requested_by,
+        }
+        if idempotency_key:
+            body["idempotency_key"] = idempotency_key
+        if link_expire_seconds:
+            body["link_expire_seconds"] = link_expire_seconds
+        return ConsentRequest(
+            **await self._request("POST", "/api/v1/consent/request/s2s", json=body)
+        )
+
+    async def get_request(self, request_id: str) -> RequestStatus:
+        return RequestStatus(
+            **await self._request("GET", "/api/v1/consent/request/status",
+                                  params={"request_id": request_id})
+        )
+
+    async def cancel(self, request_id: str) -> dict[str, Any]:
+        return await self._request("POST", f"/api/v1/consent/request/{request_id}/cancel")
+
+    async def resend(self, request_id: str) -> dict[str, Any]:
+        return await self._request("POST", f"/api/v1/consent/request/{request_id}/resend")
+
+    async def verify(self, *, consent_id: str, purpose: str) -> VerifyResult:
+        """Fail-closed gate (see CMPClient.verify)."""
+        try:
+            data = await self._request(
+                "POST", "/api/v1/consent/verify",
+                json={"consent_id": consent_id, "purpose": purpose},
+            )
+        except CMPError:
+            return VerifyResult(
+                allowed=False, status="UNKNOWN", purpose=purpose,
+                purpose_state="NOT_PRESENTED", reason="VERIFY_UNAVAILABLE",
+            )
+        return VerifyResult(**data)
+
+    async def require_consent(self, *, consent_id: str, purpose: str) -> VerifyResult:
+        res = await self.verify(consent_id=consent_id, purpose=purpose)
+        if not res.allowed:
+            _raise_not_allowed(res)
+        return res
+
+    def verify_webhook(self, headers: Mapping[str, str], body: bytes | str) -> WebhookEvent:
+        """Local (no I/O) — same as the sync client."""
+        if not self.webhook_secret:
+            raise CMPError("verify_webhook requires webhook_secret at construction")
+        sig = headers.get("X-CMP-Signature") or headers.get("x-cmp-signature")
+        if not sig:
+            raise SignatureError("missing X-CMP-Signature header")
+        raw = body.encode() if isinstance(body, str) else body
+        verify_signature(self.webhook_secret, raw, sig)
+        return WebhookEvent(**json.loads(raw))

cmp_consent/client.py

@@ -0,0 +1,166 @@
+"""Synchronous CMP consent client.
+
+Server-to-server only — holds the application API key. Never ship the key to a
+browser. See AsyncCMPClient for the awaitable variant.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Mapping
+
+import httpx
+
+from .errors import CMPError, ConsentDeclined, ConsentExpired, ConsentPending, SignatureError
+from .models import ConsentRequest, RequestStatus, VerifyResult, WebhookEvent
+from .webhooks import verify_signature
+
+
+def _envelope_error(resp: httpx.Response) -> CMPError:
+    code, message = "error", resp.text or f"HTTP {resp.status_code}"
+    try:
+        body = resp.json()
+        err = body.get("error") or body.get("detail") or {}
+        if isinstance(err, dict):
+            code = err.get("code", code)
+            message = err.get("message", message)
+        elif isinstance(err, str):
+            message = err
+    except Exception:  # noqa: BLE001 — non-JSON error body
+        pass
+    return CMPError(message, status=resp.status_code, code=code)
+
+
+def _raise_not_allowed(res: VerifyResult) -> None:
+    """Map a not-allowed VerifyResult onto a typed exception for gate flow."""
+    st = res.status
+    if st in ("EXPIRED", "CONSENT_EXPIRED"):
+        raise ConsentExpired(res.reason, code=res.reason)
+    if st in ("DECLINED", "WITHDRAWN", "CANCELLED"):
+        raise ConsentDeclined(res.reason, code=res.reason)
+    # PENDING, NOT_FOUND, PARTIALLY_GRANTED(opt-out), VERIFY_UNAVAILABLE, …
+    raise ConsentPending(res.reason, code=res.reason)
+
+
+class CMPClient:
+    """
+    cmp = CMPClient(api_base="https://cmp-api…", api_key="cmpk_live_…",
+                    webhook_secret="whsec_…")
+    """
+
+    def __init__(
+        self,
+        api_base: str,
+        api_key: str,
+        *,
+        webhook_secret: str | None = None,
+        timeout: float = 10.0,
+        retries: int = 2,
+    ):
+        self.api_base = api_base.rstrip("/")
+        self.api_key = api_key
+        self.webhook_secret = webhook_secret
+        self._http = httpx.Client(
+            base_url=self.api_base,
+            timeout=timeout,
+            headers={"X-API-Key": api_key},
+            transport=httpx.HTTPTransport(retries=retries),
+        )
+
+    # ── lifecycle ────────────────────────────────────────────────────────────
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "CMPClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def _request(self, method: str, path: str, **kw: Any) -> Any:
+        try:
+            resp = self._http.request(method, path, **kw)
+        except httpx.HTTPError as e:
+            raise CMPError(f"request failed: {e}") from e
+        if resp.status_code >= 400:
+            raise _envelope_error(resp)
+        return resp.json() if resp.content else {}
+
+    # ── request lifecycle (officer-raised) ─────────────────────────────────────
+    def create_consent_request(
+        self,
+        *,
+        email: str,
+        notice: str,
+        requested_by: str,
+        idempotency_key: str | None = None,
+        link_expire_seconds: int | None = None,
+    ) -> ConsentRequest:
+        """Raise a PENDING request; CMP emails the magic link and returns consent_id
+        at t=0. Store consent_id against your record immediately.
+
+        One request covers one notice. For two notices, make two calls — each
+        returns its own consent_id and its own link."""
+        body: dict[str, Any] = {
+            "email": email,
+            "notice_key": notice,
+            "requested_by": requested_by,
+        }
+        if idempotency_key:
+            body["idempotency_key"] = idempotency_key
+        if link_expire_seconds:
+            body["link_expire_seconds"] = link_expire_seconds
+        return ConsentRequest(**self._request("POST", "/api/v1/consent/request/s2s", json=body))
+
+    def get_request(self, request_id: str) -> RequestStatus:
+        """Poll a request's status (fallback if a webhook is missed)."""
+        return RequestStatus(
+            **self._request("GET", "/api/v1/consent/request/status",
+                            params={"request_id": request_id})
+        )
+
+    def cancel(self, request_id: str) -> dict[str, Any]:
+        """Cancel a pending request (e.g. cancel-on-save-failure). Idempotent."""
+        return self._request("POST", f"/api/v1/consent/request/{request_id}/cancel")
+
+    def resend(self, request_id: str) -> dict[str, Any]:
+        """Re-mint a fresh magic link for a still-pending request."""
+        return self._request("POST", f"/api/v1/consent/request/{request_id}/resend")
+
+    # ── the enforcement gate ───────────────────────────────────────────────────
+    def verify(self, *, consent_id: str, purpose: str) -> VerifyResult:
+        """'May I process this consent for this purpose?' FAIL-CLOSED — any error or
+        timeout returns allowed=False (never raises), so the PII is never processed
+        on an ambiguous result."""
+        try:
+            data = self._request(
+                "POST", "/api/v1/consent/verify",
+                json={"consent_id": consent_id, "purpose": purpose},
+            )
+        except CMPError:
+            return VerifyResult(
+                allowed=False, status="UNKNOWN", purpose=purpose,
+                purpose_state="NOT_PRESENTED", reason="VERIFY_UNAVAILABLE",
+            )
+        return VerifyResult(**data)
+
+    def require_consent(self, *, consent_id: str, purpose: str) -> VerifyResult:
+        """Like verify() but RAISES a typed exception when not allowed — so gated
+        code simply can't run without consent."""
+        res = self.verify(consent_id=consent_id, purpose=purpose)
+        if not res.allowed:
+            _raise_not_allowed(res)
+        return res
+
+    # ── inbound webhooks ────────────────────────────────────────────────────────
+    def verify_webhook(self, headers: Mapping[str, str], body: bytes | str) -> WebhookEvent:
+        """Validate the X-CMP-Signature over the RAW body and return the parsed event.
+        Dedupe by event.event_id, order by event.consent_seq."""
+        if not self.webhook_secret:
+            raise CMPError("verify_webhook requires webhook_secret at construction")
+        sig = headers.get("X-CMP-Signature") or headers.get("x-cmp-signature")
+        if not sig:
+            raise SignatureError("missing X-CMP-Signature header")
+        raw = body.encode() if isinstance(body, str) else body
+        verify_signature(self.webhook_secret, raw, sig)
+        return WebhookEvent(**json.loads(raw))

cmp_consent/errors.py

@@ -0,0 +1,32 @@
+"""Typed exceptions for the CMP consent SDK.
+
+Callers map these to control flow: a gate that raises ConsentPending/Declined/Expired
+means "do not process the PII"; CMPError is any other failure (network, 4xx/5xx).
+"""
+
+from __future__ import annotations
+
+
+class CMPError(Exception):
+    """Base error. Carries the backend envelope code + HTTP status when available."""
+
+    def __init__(self, message: str, *, status: int | None = None, code: str | None = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class ConsentPending(CMPError):
+    """The consent has been requested but not yet granted — processing must wait."""
+
+
+class ConsentDeclined(CMPError):
+    """The principal declined (or withdrew) — processing is not permitted."""
+
+
+class ConsentExpired(CMPError):
+    """The consent/request has expired — a fresh request or re-consent is needed."""
+
+
+class SignatureError(CMPError):
+    """An inbound webhook's X-CMP-Signature failed verification (forged/replayed)."""

cmp_consent/models.py

@@ -0,0 +1,78 @@
+"""Typed request/response models (Pydantic v2)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel
+
+
+class ConsentRequest(BaseModel):
+    """Returned by create_consent_request — `consent_id` is the durable key to store
+    against the PII from t=0."""
+    consent_id: str
+    request_id: str
+    status: str
+    request_ref: str
+    magic_link: Optional[str] = None   # only when email mode = return_link
+
+
+class RequestStatus(BaseModel):
+    request_id: str
+    consent_id: str
+    status: str   # PENDING|GRANTED|PARTIALLY_GRANTED|DECLINED|EXPIRED|CANCELLED|SUPERSEDED
+
+
+class VerifyResult(BaseModel):
+    """The enforcement gate result. `allowed` is the only thing to branch on for
+    processing; the rest is for auditing/telemetry."""
+    allowed: bool
+    status: str
+    purpose: str
+    purpose_state: str
+    reason: str
+    consent_record_id: Optional[str] = None   # set only when allowed
+    integrity_hash: Optional[str] = None       # audit proof, set only when allowed
+    consent_seq: Optional[int] = None
+    needs_reconsent: bool = False
+    expires_at: Optional[str] = None
+
+
+class WebhookEvent(BaseModel):
+    """A verified inbound webhook (envelope). Use `type`, `consent_id`, `consent_seq`
+    to route + dedupe (by `event_id`)."""
+    event_id: str
+    event_type: str
+    application_id: Optional[str] = None
+    occurred_at: str
+    data: Dict[str, Any] = {}   # Dict (not dict[...]) so the model builds on Python 3.8
+
+    @property
+    def type(self) -> str:
+        return self.event_type
+
+    @property
+    def consent_id(self) -> Optional[str]:
+        return self.data.get("consent_id")
+
+    @property
+    def request_id(self) -> Optional[str]:
+        return self.data.get("request_id")
+
+    @property
+    def consent_seq(self) -> Optional[int]:
+        return self.data.get("consent_seq")
+
+    @property
+    def decision(self) -> Optional[str]:
+        """FULL | PARTIAL | DECLINED (grant/decline events)."""
+        return self.data.get("decision")
+
+    @property
+    def granted_purposes(self) -> list[str]:
+        """Purpose CODES the principal opted in to — for a direct membership check."""
+        return self.data.get("granted_purposes", [])
+
+    @property
+    def denied_purposes(self) -> list[str]:
+        return self.data.get("denied_purposes", [])

cmp_consent/webhooks.py

@@ -0,0 +1,48 @@
+"""Inbound webhook signature verification.
+
+CMP signs each delivery Stripe/GitHub-style:
+    header  X-CMP-Signature: t=<unix_ts>,v1=<hex hmac_sha256>
+    signed  "<ts>." + <raw body bytes>   (key = the subscription's whsec_ secret)
+
+Verifying the raw body (not a re-serialized dict) is essential — the signature is
+over the exact bytes CMP sent.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+
+from .errors import SignatureError
+
+
+def _parse_header(header: str) -> tuple[str, str]:
+    parts = dict(
+        p.split("=", 1) for p in header.split(",") if "=" in p
+    )
+    ts, sig = parts.get("t"), parts.get("v1")
+    if not ts or not sig:
+        raise SignatureError("malformed X-CMP-Signature header")
+    return ts, sig
+
+
+def verify_signature(
+    secret: str, payload: bytes, header: str, *, tolerance_seconds: int = 300
+) -> None:
+    """Raise SignatureError unless `header` is a valid signature of `payload`.
+
+    tolerance_seconds guards against replay (0 disables the timestamp check).
+    """
+    ts, sig = _parse_header(header)
+    signed = ts.encode() + b"." + payload
+    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, sig):
+        raise SignatureError("webhook signature mismatch")
+    if tolerance_seconds:
+        try:
+            drift = abs(time.time() - int(ts))
+        except ValueError as e:
+            raise SignatureError("bad signature timestamp") from e
+        if drift > tolerance_seconds:
+            raise SignatureError("webhook timestamp outside tolerance")

cmp_consent-0.1.1.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: cmp-consent
+Version: 0.1.1
+Summary: Python SDK for the CMP officer-assisted deferred consent flow (raise requests, gate on verify, verify webhooks).
+Author: Pentafox
+License: Proprietary
+Keywords: cmp,compliance,consent,dpdp,privacy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cmp-consent
+
+Python SDK for the CMP **officer-assisted deferred consent** flow. Runs in your
+backend (server-to-server) and holds the application API key — never ship the key to
+a browser.
+
+Three jobs: **raise** consent requests, **gate** PII processing on `verify()`, and
+**verify** CMP's signed webhooks.
+
+## Install
+
+```bash
+pip install cmp-consent
+```
+
+## Authentication
+
+| Credential | Direction | Header |
+|---|---|---|
+| API key `cmpk_live_…` | SDK → CMP | `X-API-Key` (application-scoped) |
+| Webhook secret `whsec_…` | CMP → SDK | HMAC `X-CMP-Signature` (for `verify_webhook`) |
+
+```python
+from cmp_consent import CMPClient
+
+cmp = CMPClient(
+    api_base="https://cmp-api.yourdomain",
+    api_key="cmpk_live_…",
+    webhook_secret="whsec_…",   # only needed for verify_webhook
+    timeout=10, retries=2,
+)
+```
+
+## 1) Raise a request (officer submitted)
+
+```python
+req = cmp.create_consent_request(
+    email="user@example.com",
+    notice="kyc-notice",           # the notice key for the application
+    requested_by=officer.id,
+    idempotency_key=submit_id,     # a retried submit won't double-send the email
+)
+save(applicant_id, consent_id=req.consent_id)   # store consent_id at t=0
+```
+
+CMP creates a PENDING request, emails the principal a single-use magic link, and
+returns `consent_id` immediately.
+
+## 2) Gate every use of the PII
+
+```python
+from cmp_consent import ConsentPending
+
+res = cmp.verify(consent_id=req.consent_id, purpose="bureau_pull")
+if not res.allowed:
+    raise ConsentPending(res.reason)     # PENDING/DECLINED/EXPIRED → do not process
+proceed(proof=res.integrity_hash)        # allowed → consent-backed
+```
+
+`verify()` is **fail-closed**: any network error or timeout returns `allowed=False`
+(it never raises), so PII is never processed on an ambiguous result. Prefer
+`require_consent(...)` when you want it to raise instead:
+
+```python
+cmp.require_consent(consent_id=cid, purpose="bureau_pull")   # raises if not granted
+```
+
+## 3) Receive the callback
+
+```python
+# in your webhook route — pass the RAW body bytes
+event = cmp.verify_webhook(request.headers, request.body)
+if event.type == "CONSENT_GRANTED" and is_new(event.event_id):   # dedupe by event_id
+    unblock(event.consent_id)
+```
+
+Webhooks are at-least-once and unordered: **dedupe by `event.event_id`, order by
+`event.consent_seq`**, and treat `verify()` as the source of truth on any ambiguity.
+
+## Manage
+
+```python
+cmp.get_request(req.request_id)   # poll status (fallback if a webhook is missed)
+cmp.resend(req.request_id)        # re-mint an expired magic link
+cmp.cancel(req.request_id)        # cancel-on-save-failure
+```
+
+## Async
+
+`AsyncCMPClient` mirrors the same surface with `await`:
+
+```python
+from cmp_consent import AsyncCMPClient
+
+async with AsyncCMPClient(api_base=…, api_key=…) as cmp:
+    req = await cmp.create_consent_request(email=e, notice="kyc-notice", requested_by=o)
+    res = await cmp.verify(consent_id=req.consent_id, purpose="bureau_pull")
+```
+
+## Exceptions
+
+`ConsentPending` · `ConsentDeclined` · `ConsentExpired` · `SignatureError` ·
+`CMPError` (base). Each carries `.status` (HTTP) and `.code` (envelope code) when
+available.

cmp_consent-0.1.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+cmp_consent/__init__.py,sha256=JGwZynmXqyJUbeeJUooyu1znCAzCJzny_-xL_rMDxgI,905
+cmp_consent/aio.py,sha256=1sZjHagewU_SWgGoH0DFT8Jr6tFiw_axA5b5i7FD9MQ,4426
+cmp_consent/client.py,sha256=ltP-q0lXpMqPUuvQgTHZkBefVWj0S46eTdeZtW7q2yg,7147
+cmp_consent/errors.py,sha256=S_r96YYvT7vXBnpxLpeUJkf6XbuwOkOt_4oNKYKLoOY,1060
+cmp_consent/models.py,sha256=JVoptfHzrm4TevpE9_WVyPIk8_LeHhGwDTUrXM_RvQU,2435
+cmp_consent/webhooks.py,sha256=JqxO97fFrb3XpoqMZlWoEWVwrQj9qQ33G62RywYyF4g,1644
+cmp_consent-0.1.1.dist-info/METADATA,sha256=3MRnmLKEcsR2CTXL8NWvjFdVJu6tqzXO1wwvRyqOAhw,4196
+cmp_consent-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+cmp_consent-0.1.1.dist-info/RECORD,,

cmp_consent-0.1.1.dist-info/WHEEL

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