dpdpguard-sdk 1.0.0__py3-none-any.whl

dpdpguard/__init__.py

@@ -0,0 +1,24 @@
+"""DPDP Guard Server SDK (Python) - typed API client, consent gate, token broker, webhook verifier"""
+
+from .audit_hash import AuditHashInput, canonicalize_audit_event, compute_audit_hash
+from .client import DpdpGuardClient
+from .consent_gate import ConsentRecord, has_consent
+from .errors import ERROR_CATALOG, ApiErrorCode, DpdpGuardApiError, ErrorCatalogEntry
+from .webhook_verifier import verify_webhook_signature
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "ERROR_CATALOG",
+    "ApiErrorCode",
+    "AuditHashInput",
+    "ConsentRecord",
+    "DpdpGuardApiError",
+    "DpdpGuardClient",
+    "ErrorCatalogEntry",
+    "__version__",
+    "canonicalize_audit_event",
+    "compute_audit_hash",
+    "has_consent",
+    "verify_webhook_signature",
+]

dpdpguard/_data/audit-hash-vectors.json

@@ -0,0 +1,62 @@
+{
+	"_description": "Golden vectors for convex/lib/auditHash.ts (ADR-002 D5). HMAC-SHA256 per DPO sign-off decision (conformance/dpo-sign-off-request.md item 1) — the platform's key, not the fixed test secret used to derive these vectors, is the production key. Do not hand-edit expectedCanonical/expectedHash without re-deriving them from the spec's canonicalization rules and the same test secret documented in audit-hash-spec.md.",
+	"testSecret": "test-only-audit-hash-hmac-secret-do-not-use-in-production",
+	"vectors": [
+		{
+			"name": "simple direct grant",
+			"input": {
+				"organizationId": "org_abc123",
+				"noticeId": "notice_v1",
+				"noticeVersion": 1,
+				"purpose": "Newsletter",
+				"dataTypes": ["email"],
+				"givenAt": 1700000000000,
+				"source": "direct"
+			},
+			"expectedCanonical": "org_abc123|notice_v1|1|Newsletter|email|1700000000000|direct",
+			"expectedHash": "9b72403de808d11a55b473e268407cac809e9c63604f9a14a9d8cd3128990cdd"
+		},
+		{
+			"name": "dataTypes sorted regardless of input order",
+			"input": {
+				"organizationId": "org_abc123",
+				"noticeId": "notice_v1",
+				"noticeVersion": 1,
+				"purpose": "Marketing",
+				"dataTypes": ["phone", "email"],
+				"givenAt": 1700000001000,
+				"source": "brokered"
+			},
+			"expectedCanonical": "org_abc123|notice_v1|1|Marketing|email,phone|1700000001000|brokered",
+			"expectedHash": "d8d67169d5b11319783e1791d1f191b076d1c9c79c664a6a5ab85ae5500da3ce"
+		},
+		{
+			"name": "anonymous source, later notice version",
+			"input": {
+				"organizationId": "org_abc123",
+				"noticeId": "notice_v2",
+				"noticeVersion": 2,
+				"purpose": "Analytics",
+				"dataTypes": ["deviceId"],
+				"givenAt": 1700000002000,
+				"source": "anonymous"
+			},
+			"expectedCanonical": "org_abc123|notice_v2|2|Analytics|deviceId|1700000002000|anonymous",
+			"expectedHash": "deda978c9479971fad39d3a5b7d385bd603e5497b6a99d988ec8cc865cf72dc0"
+		},
+		{
+			"name": "null source serializes as the literal string \"null\"",
+			"input": {
+				"organizationId": "org_abc123",
+				"noticeId": "notice_v1",
+				"noticeVersion": 1,
+				"purpose": "Newsletter",
+				"dataTypes": ["email"],
+				"givenAt": 1700000003000,
+				"source": null
+			},
+			"expectedCanonical": "org_abc123|notice_v1|1|Newsletter|email|1700000003000|null",
+			"expectedHash": "687ad4b322efb6ccc620d2d3ef7b8e115f06e74725819e72dd79bf1250d802e8"
+		}
+	]
+}

dpdpguard/_data/error-catalog.json

@@ -0,0 +1,45 @@
+{
+  "$comment": "ADR-002 D2: the machine-readable error catalog for /api/v1. Mirrors convex/lib/apiErrors.ts's API_ERROR_CODES 1:1 — convex/lib/apiErrors.test.ts enforces this file cannot drift out of sync with the source. Adding a code here is additive (minor); changing an existing code's meaning is breaking (major) under ADR-002 D4.",
+  "codes": [
+    {
+      "code": "MINOR_TRACKING_BLOCKED",
+      "description": "Tracking/analytics consent is disabled for a verified minor and cannot be granted."
+    },
+    {
+      "code": "NOTICE_NOT_PUBLISHED",
+      "description": "The referenced notice exists but is not in a published state."
+    },
+    {
+      "code": "ALREADY_CONSENTED",
+      "description": "A consent decision already exists for this (user, notice, purpose) and the request would duplicate it."
+    },
+    {
+      "code": "NOT_ASSOCIATED_WITH_ORG",
+      "description": "The authenticated principal does not belong to the organization the request targets."
+    },
+    {
+      "code": "INVALID_STATUS_TRANSITION",
+      "description": "The requested status change is not a valid transition from the resource's current status."
+    },
+    {
+      "code": "SDK_VERSION_UNSUPPORTED",
+      "description": "The calling SDK's version is below the server's configured minimum-supported floor (ADR-002 D6)."
+    },
+    {
+      "code": "NOT_FOUND",
+      "description": "The requested resource does not exist or is not visible to the authenticated principal."
+    },
+    {
+      "code": "UNAUTHORIZED",
+      "description": "The request is missing valid authentication or the credential does not grant access to this resource."
+    },
+    {
+      "code": "RATE_LIMITED",
+      "description": "The request was rejected because the caller exceeded a rate limit."
+    },
+    {
+      "code": "VALIDATION_ERROR",
+      "description": "The request failed validation and no more specific code applies; the human-readable error message has details."
+    }
+  ]
+}

dpdpguard/audit_hash.py

@@ -0,0 +1,51 @@
+"""Server-side reimplementation of ``convex/lib/auditHash.ts``'s canonicalization
+(conformance/audit-hash-spec.md), so a holder of ``DPDP_AUDIT_HASH_HMAC_SECRET``
+can independently verify a ``consentAuditTrail`` row's ``auditHash`` rather than
+trusting it blindly.
+
+Verified against the vendored golden vectors in ``_data/audit-hash-vectors.json``
+(ADR-002 D5) — see ``tests/test_audit_hash.py``. Any change to this
+canonicalization is a **major** version bump, since it breaks comparability of
+the immutable, long-retained audit trail.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+AuditSource = Optional[Literal["brokered", "direct", "anonymous", "linked"]]
+
+
+@dataclass(frozen=True)
+class AuditHashInput:
+    organization_id: str
+    notice_id: str
+    notice_version: int
+    purpose: str
+    data_types: list[str]
+    given_at: int
+    source: AuditSource
+
+
+def canonicalize_audit_event(input: AuditHashInput) -> str:
+    sorted_data_types = ",".join(sorted(input.data_types))
+    source = input.source if input.source is not None else "null"
+    return "|".join(
+        [
+            input.organization_id,
+            input.notice_id,
+            str(input.notice_version),
+            input.purpose,
+            sorted_data_types,
+            str(input.given_at),
+            source,
+        ]
+    )
+
+
+def compute_audit_hash(input: AuditHashInput, secret: str) -> str:
+    canonical = canonicalize_audit_event(input)
+    return hmac.new(secret.encode("utf-8"), canonical.encode("utf-8"), hashlib.sha256).hexdigest()

dpdpguard/client.py

@@ -0,0 +1,221 @@
+"""Thin typed client over DPDP Guard's public ``/api/v1`` (spec §4.2).
+
+Mirrors ``@dpdpguard/server`` (the Node/TypeScript reference SDK) method for
+method, so behavior — auth modes, idempotency headers, error mapping — stays
+identical across ecosystems per ADR-001's audit-uniformity goal.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+from urllib.parse import quote, urlencode
+
+import httpx
+
+from .errors import DpdpGuardApiError
+from .models import (
+    BannerConfig,
+    BrokerTokenResult,
+    DsrRequest,
+    DsrRequestsResponse,
+    DsrType,
+    Grievance,
+    GrievancesResponse,
+    LinkAnonymousConsentResult,
+    Nomination,
+    Notice,
+    NoticesResponse,
+    OrgSummary,
+)
+
+AuthMode = Literal["none", "apiKey", "bearer"]
+
+_SDK_VERSION = "1.0.0"
+
+
+class DpdpGuardClient:
+    """Typed client over ``/api/v1``.
+
+    Parameters
+    ----------
+    base_url:
+        e.g. ``"https://trustworthy-alligator-303.convex.site"``.
+    api_key:
+        Service API key (``convex/apiKeys.ts``) — required for :meth:`broker_token`.
+    access_token:
+        A brokered principal access token, if you already minted one.
+    http_client:
+        Override for testing/transport customization; defaults to a new
+        :class:`httpx.Client`. The client owns and closes it unless one was
+        passed in.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key: str | None = None,
+        access_token: str | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._access_token = access_token
+        self._owns_http_client = http_client is None
+        self._http = http_client if http_client is not None else httpx.Client()
+
+    def close(self) -> None:
+        if self._owns_http_client:
+            self._http.close()
+
+    def __enter__(self) -> DpdpGuardClient:  # noqa: PYI034 (avoid a typing_extensions dep for Self on py3.9-3.10)
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def set_access_token(self, token: str) -> None:
+        """Set/replace the brokered principal access token (e.g. after re-brokering on expiry)."""
+        self._access_token = token
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, object] | None = None,
+        auth: AuthMode = "bearer",
+        headers: dict[str, str] | None = None,
+    ) -> object:
+        request_headers = {"X-DPDP-SDK": f"python/{_SDK_VERSION}"}
+        if headers:
+            request_headers.update(headers)
+
+        if auth == "apiKey":
+            if not self._api_key:
+                raise RuntimeError(
+                    "DpdpGuardClient: this call requires `api_key` to be set in the constructor."
+                )
+            request_headers["Authorization"] = f"Bearer {self._api_key}"
+        elif auth == "bearer":
+            if not self._access_token:
+                raise RuntimeError(
+                    "DpdpGuardClient: this call requires an access token — call "
+                    "broker_token() first, or pass `access_token` in the constructor."
+                )
+            request_headers["Authorization"] = f"Bearer {self._access_token}"
+
+        response = self._http.request(
+            method,
+            f"{self._base_url}{path}",
+            json=json,
+            headers=request_headers,
+        )
+
+        body = response.text
+        data = response.json() if body else None
+
+        if not response.is_success:
+            code = "VALIDATION_ERROR"
+            message = f"Request failed with status {response.status_code}"
+            if isinstance(data, dict):
+                code = str(data.get("code", code))
+                message = str(data.get("error", message))
+            raise DpdpGuardApiError(code, message, response.status_code)
+
+        return data
+
+    # --- Public reads (no auth) ---
+
+    def get_organization(self, slug: str) -> OrgSummary:
+        return self._request("GET", f"/api/v1/org/{quote(slug)}", auth="none")  # type: ignore[return-value]
+
+    def get_notices(self, org_id: str) -> NoticesResponse:
+        return self._request(  # type: ignore[return-value]
+            "GET", f"/api/v1/org/{quote(org_id)}/notices", auth="none"
+        )
+
+    def get_notice(self, notice_id: str) -> Notice:
+        return self._request("GET", f"/api/v1/notices/{quote(notice_id)}", auth="none")  # type: ignore[return-value]
+
+    def get_banner_config(
+        self,
+        org_id: str,
+        *,
+        domain: str | None = None,
+        app_id: str | None = None,
+    ) -> BannerConfig:
+        query = {}
+        if domain:
+            query["domain"] = domain
+        if app_id:
+            query["appId"] = app_id
+        qs = f"?{urlencode(query)}" if query else ""
+        return self._request(  # type: ignore[return-value]
+            "GET", f"/api/v1/org/{quote(org_id)}/banner-config{qs}", auth="none"
+        )
+
+    # --- Auth (ADR-004) ---
+
+    def broker_token(self, external_id: str) -> BrokerTokenResult:
+        """Mints a brokered principal access token using the service API key,
+        and stores it for subsequent calls."""
+        result: BrokerTokenResult = self._request(  # type: ignore[assignment]
+            "POST",
+            "/api/v1/auth/broker-token",
+            json={"externalId": external_id},
+            auth="apiKey",
+        )
+        self._access_token = result["accessToken"]
+        return result
+
+    def link_anonymous_consent(self, anonymous_id: str) -> LinkAnonymousConsentResult:
+        return self._request(  # type: ignore[return-value]
+            "POST", "/api/v1/link-anonymous-consent", json={"anonymousId": anonymous_id}
+        )
+
+    # --- DSR (spec §4.2) ---
+
+    def list_dsr_requests(self) -> DsrRequestsResponse:
+        return self._request("GET", "/api/v1/dsr")  # type: ignore[return-value]
+
+    def create_dsr_request(
+        self,
+        *,
+        organization_id: str,
+        type: DsrType,
+        details: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> DsrRequest:
+        body: dict[str, object] = {"organizationId": organization_id, "type": type}
+        if details is not None:
+            body["details"] = details
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._request("POST", "/api/v1/dsr", json=body, headers=headers)  # type: ignore[return-value]
+
+    # --- Grievances (spec §4.2) ---
+
+    def list_grievances(self) -> GrievancesResponse:
+        return self._request("GET", "/api/v1/grievances")  # type: ignore[return-value]
+
+    def create_grievance(self, *, organization_id: str, subject: str, description: str) -> Grievance:
+        return self._request(  # type: ignore[return-value]
+            "POST",
+            "/api/v1/grievances",
+            json={"organizationId": organization_id, "subject": subject, "description": description},
+        )
+
+    # --- Nomination (spec §4.2) ---
+
+    def get_nomination(self) -> Nomination | None:
+        return self._request("GET", "/api/v1/nomination")  # type: ignore[return-value]
+
+    def upsert_nomination(self, *, nominee_name: str, nominee_contact: str) -> Nomination:
+        return self._request(  # type: ignore[return-value]
+            "PUT",
+            "/api/v1/nomination",
+            json={"nomineeName": nominee_name, "nomineeContact": nominee_contact},
+        )
+
+    def revoke_nomination(self) -> dict[str, object]:
+        return self._request("DELETE", "/api/v1/nomination")  # type: ignore[return-value]

dpdpguard/consent_gate.py

@@ -0,0 +1,22 @@
+"""Pure helper for gating a feature/tracker on an existing consent decision —
+e.g. ``if not has_consent(consents, "Analytics"): return`` before firing an
+analytics event. Does not call the network; combine with
+:meth:`~dpdpguard.client.DpdpGuardClient.list_dsr_requests`-style reads or
+your own cached consent state.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Protocol
+
+
+class ConsentRecord(Protocol):
+    """Anything with a ``purpose`` and an optional ``withdrawn_at``."""
+
+    purpose: str
+    withdrawn_at: int | None
+
+
+def has_consent(consents: Sequence[ConsentRecord], purpose: str) -> bool:
+    return any(c.purpose == purpose and c.withdrawn_at is None for c in consents)

dpdpguard/errors.py

@@ -0,0 +1,51 @@
+"""ADR-002 D2's typed error-code catalog for ``/api/v1``.
+
+Vendored from ``@dpdpguard/contract/conformance/error-catalog.json`` (see
+``_data/error-catalog.json``) rather than hand-copied, so drift from the
+platform's canonical catalog is a file diff, not a silent mismatch.
+"""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+from typing import Literal, TypedDict
+
+ApiErrorCode = Literal[
+    "MINOR_TRACKING_BLOCKED",
+    "NOTICE_NOT_PUBLISHED",
+    "ALREADY_CONSENTED",
+    "NOT_ASSOCIATED_WITH_ORG",
+    "INVALID_STATUS_TRANSITION",
+    "SDK_VERSION_UNSUPPORTED",
+    "NOT_FOUND",
+    "UNAUTHORIZED",
+    "RATE_LIMITED",
+    "VALIDATION_ERROR",
+]
+
+
+class ErrorCatalogEntry(TypedDict):
+    code: str
+    description: str
+
+
+def _load_catalog() -> list[ErrorCatalogEntry]:
+    raw = resources.files("dpdpguard._data").joinpath("error-catalog.json").read_text("utf-8")
+    codes: list[ErrorCatalogEntry] = json.loads(raw)["codes"]
+    return codes
+
+
+ERROR_CATALOG: list[ErrorCatalogEntry] = _load_catalog()
+
+
+class DpdpGuardApiError(Exception):
+    """Raised by :class:`~dpdpguard.client.DpdpGuardClient` for any non-2xx response."""
+
+    def __init__(self, code: str, message: str, status: int) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"DpdpGuardApiError(code={self.code!r}, status={self.status!r}, message={str(self)!r})"

dpdpguard/models.py

@@ -0,0 +1,96 @@
+"""Typed wire shapes for DPDP Guard's public ``/api/v1`` (spec §4.2), hand-kept
+in sync with ``openapi/v1.yaml``'s ``components.schemas``. Field names are the
+exact JSON keys (camelCase) the API sends/expects — no snake_case remapping —
+so what you see here is what's on the wire.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class OrgSummary(TypedDict):
+    orgId: str
+    name: str
+    slug: str
+
+
+class NoticeItemized(TypedDict):
+    purpose: str
+    personalDataDescription: str
+
+
+class Notice(TypedDict):
+    _id: str
+    organizationId: str
+    version: int
+    itemized: list[NoticeItemized]
+    content: dict[str, object]
+    status: str  # "draft" | "published"
+
+
+class _DsrRequestRequired(TypedDict):
+    requestId: str
+    type: str  # "summary" | "processors" | "correction" | "erasure"
+    status: str  # "pending" | "in_progress" | "completed" | "rejected"
+
+
+class DsrRequest(_DsrRequestRequired, total=False):
+    dueAt: int
+    requestDetails: str
+
+
+class _GrievanceRequired(TypedDict):
+    grievanceId: str
+    subject: str
+    description: str
+    status: str  # "open" | "in_progress" | "resolved"
+    dueAt: int
+
+
+class Grievance(_GrievanceRequired, total=False):
+    respondedAt: int
+    response: str
+
+
+class Nomination(TypedDict):
+    nominationId: str
+    nomineeName: str
+    nomineeContact: str
+    status: str  # "active" | "revoked"
+
+
+class BannerConfig(TypedDict, total=False):
+    bannerSettings: dict[str, object]
+    configVersion: int
+
+
+class BrokerTokenResult(TypedDict):
+    accessToken: str
+    expiresAt: int
+    tokenType: str
+
+
+class NeedsReconsentEntry(TypedDict):
+    noticeId: str
+    purpose: str
+
+
+class LinkAnonymousConsentResult(TypedDict):
+    linkedCount: int
+    needsReconsent: list[NeedsReconsentEntry]
+
+
+class NoticesResponse(TypedDict):
+    notices: list[Notice]
+
+
+class DsrRequestsResponse(TypedDict):
+    requests: list[DsrRequest]
+
+
+class GrievancesResponse(TypedDict):
+    grievances: list[Grievance]
+
+
+DsrType = str  # "summary" | "processors" | "correction" | "erasure"

dpdpguard/py.typed

@@ -0,0 +1 @@
+

dpdpguard/webhook_verifier.py

@@ -0,0 +1,35 @@
+"""Verifies the ``X-DPDP-Signature`` header set by ``convex/webhooks.ts``'s
+``deliverToEndpoint`` (HMAC-SHA256 over the raw JSON body, hex-encoded, using
+the webhook endpoint's own secret — not the audit-hash secret).
+
+``raw_body`` must be the exact bytes/string received on the wire, before any
+``json.loads`` — HMACs are sensitive to whitespace/key-order, so
+re-serializing a parsed object and hashing that will not match.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+def verify_webhook_signature(
+    secret: str,
+    raw_body: str | bytes,
+    signature_header: str | None,
+) -> bool:
+    if not signature_header:
+        return False
+
+    body_bytes = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+    expected = hmac.new(secret.encode("utf-8"), body_bytes, hashlib.sha256).hexdigest()
+
+    try:
+        expected_bytes = bytes.fromhex(expected)
+        actual_bytes = bytes.fromhex(signature_header)
+    except ValueError:
+        return False
+
+    if len(expected_bytes) != len(actual_bytes):
+        return False
+    return hmac.compare_digest(expected_bytes, actual_bytes)

dpdpguard_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: dpdpguard-sdk
+Version: 1.0.0
+Summary: DPDP Guard Server SDK (Python) - typed API client, consent gate, token broker, webhook verifier
+Project-URL: Homepage, https://github.com/dpdp-guard-ai/dpdpguard-python-sdk
+Project-URL: Spec, https://github.com/chintans/dpdpbot/blob/main/docs/specs/mobile-server-sdk.md
+Author: DPDP Guard
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dpdpguard-python-sdk
+
+DPDP Guard Server SDK (Python) — typed API client, consent gate, token broker
+helper, audit-hash verifier, and webhook signature verifier over DPDP Guard's
+public `/api/v1` (spec §4.2).
+
+PyPI distribution: `dpdpguard-sdk` · Import as: `dpdpguard`
+
+Part of the DPDP Guard SDK family. See the design spec:
+https://github.com/chintans/dpdpbot/blob/main/docs/specs/mobile-server-sdk.md
+
+This SDK mirrors [`@dpdpguard/server`](https://www.npmjs.com/package/@dpdpguard/server)
+(the Node/TypeScript reference implementation) method for method, so behavior —
+auth modes, idempotency headers, error codes, audit-hash canonicalization — stays
+identical across ecosystems (ADR-001's audit-uniformity goal).
+
+## Install
+
+```bash
+pip install dpdpguard-sdk
+```
+
+## Usage
+
+```python
+import os
+from dpdpguard import DpdpGuardClient, has_consent, verify_webhook_signature
+
+client = DpdpGuardClient(
+    "https://<your-deployment>.convex.site",
+    api_key=os.environ["DPDP_SERVICE_API_KEY"],  # convex/apiKeys.ts, for broker_token() only
+)
+
+# Mint a brokered principal access token (ADR-004 D1/D2) for a known user.
+client.broker_token(external_id)
+
+# Now authenticated calls use that token automatically.
+result = client.list_dsr_requests()
+client.create_dsr_request(organization_id=org_id, type="erasure")
+
+# Public reads need no auth at all.
+org = client.get_organization("acme")
+notices = client.get_notices(org["orgId"])
+
+# Verify an inbound webhook (convex/webhooks.ts's X-DPDP-Signature header).
+ok = verify_webhook_signature(webhook_secret, raw_body, request.headers.get("x-dpdp-signature"))
+```
+
+Use it as a context manager to close the underlying `httpx.Client` automatically:
+
+```python
+with DpdpGuardClient(base_url) as client:
+    org = client.get_organization("acme")
+```
+
+Every non-2xx response raises a `DpdpGuardApiError` with a `code` from the
+ADR-002 error catalog (`err.code`, e.g. `"NOT_FOUND"`) and the HTTP `status`.
+
+### Consent gate
+
+```python
+from dpdpguard import has_consent
+
+if not has_consent(consents, "Marketing"):
+    return  # don't send the campaign
+```
+
+### Audit-hash verification
+
+A holder of the platform's `DPDP_AUDIT_HASH_HMAC_SECRET` can independently
+verify a `consentAuditTrail` row's `auditHash`:
+
+```python
+from dpdpguard import AuditHashInput, compute_audit_hash
+
+input = AuditHashInput(
+    organization_id="org_abc123",
+    notice_id="notice_v1",
+    notice_version=1,
+    purpose="Newsletter",
+    data_types=["email"],
+    given_at=1700000000000,
+    source="direct",
+)
+assert compute_audit_hash(input, secret) == stored_audit_hash
+```
+
+## Contract
+
+This package vendors its wire contract from `dpdpbot`'s single source of
+truth (ADR-001/002) rather than depending on a published `@dpdpguard/contract`
+Python package (none exists yet):
+
+- `src/dpdpguard/models.py` is hand-kept in sync with `openapi/v1.yaml`'s
+  `components.schemas`.
+- `src/dpdpguard/errors.py` loads `_data/error-catalog.json`, vendored
+  verbatim from `@dpdpguard/contract/conformance/error-catalog.json`
+  (ADR-002 D2).
+- `tests/test_audit_hash.py` runs `_data/audit-hash-vectors.json` (vendored
+  from `@dpdpguard/contract/conformance/audit-hash-vectors.json`) as a
+  required CI gate (ADR-002 D5) — a failure means this SDK's `audit_hash.py`
+  has drifted from `convex/lib/auditHash.ts`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+mypy src
+pytest --cov=src --cov-report=term-missing
+```

dpdpguard_sdk-1.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+dpdpguard/__init__.py,sha256=HKgBmFPNYJr3tJ_32zWu9dUzpSjbQ6uePwAmIbfX6RQ,741
+dpdpguard/audit_hash.py,sha256=qZ0rLynkdd9Ir7WySdKPh-yb6f_bbH5KA28elQlf5MA,1621
+dpdpguard/client.py,sha256=o3mnXZEn-oFNImfssWtvlKJUnLYcuw-ueXB86ZwgUH8,7659
+dpdpguard/consent_gate.py,sha256=hbXjkUh4M4akgS9pxctvi8Ppfqee_KEcl3y3JVCDLik,735
+dpdpguard/errors.py,sha256=2fjPFCPVrZ8P3VlTPiokw8cQ0h7U4zKDEhcvZG5vcpc,1496
+dpdpguard/models.py,sha256=mQmtG20hykGRqrijb1tFpzkg8Vqw1gYIjZpjPpXAFes,2061
+dpdpguard/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+dpdpguard/webhook_verifier.py,sha256=MMi-nGtDlq51RbQBhYE9gfXLXVSlDyNCtgjH90vvT5g,1132
+dpdpguard/_data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dpdpguard/_data/audit-hash-vectors.json,sha256=pYWH7mrlj4bzxSbMtoE5oGCpnK1BBCzrIdUEHQbWMvg,2371
+dpdpguard/_data/error-catalog.json,sha256=WdHQT9pvtEOlJsIc2mUihwndEy6oK9zZLX6D35u-SPo,1966
+dpdpguard_sdk-1.0.0.dist-info/METADATA,sha256=jKiK7TFK2NVHIdZIJpu4ZhUngVQyAH4ic8TABvSc5Zo,4609
+dpdpguard_sdk-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+dpdpguard_sdk-1.0.0.dist-info/licenses/LICENSE,sha256=tIblXvn9CRrr69XHSSfcMqRvnjP9g9bdfArbTQRCVs8,1098
+dpdpguard_sdk-1.0.0.dist-info/RECORD,,

dpdpguard_sdk-1.0.0.dist-info/WHEEL

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

dpdpguard_sdk-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2026 Chintan Shah
+
+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
+(including the next paragraph) 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.