dpdpkit-core 0.1.0a1__py3-none-any.whl

dpdpkit/__init__.py

@@ -0,0 +1,82 @@
+"""dpdpkit — developer primitives for India's DPDP Act, 2023 and DPDP Rules, 2025.
+
+dpdpkit helps you implement obligations; it does not provide legal advice or guarantee compliance.
+"""
+
+# Adapters ship subpackages (``dpdpkit.fastapi``, ``dpdpkit.django``) from separate distributions.
+from pkgutil import extend_path
+
+__path__ = extend_path(__path__, __name__)
+
+__version__ = "0.1.0a1"
+
+from .config import kit_from_config, load_config, sync_notice
+from .errors import (
+    ConfigError,
+    ConsentRequired,
+    DpdpkitError,
+    InvalidTransition,
+    LedgerTampered,
+    NotFound,
+    NoticeInvalid,
+    PolicyError,
+    ValidationFailed,
+)
+from .kit import ContactResolver, Kit
+from .models import (
+    ConsentStatus,
+    Contact,
+    DataItem,
+    LegalBasis,
+    Processor,
+    Purpose,
+    RequestKind,
+    RequestStatus,
+    RetentionRule,
+    RetentionTrigger,
+    Role,
+    ScheduleStatus,
+)
+from .notify import ConsoleNotifier, MemoryNotifier, Notifier, NullNotifier, SmtpNotifier
+from .policy import Policy
+from .registry import Registry
+from .repository import InMemoryRepository, Repository
+
+__all__ = [
+    "ConfigError",
+    "ConsentRequired",
+    "ConsentStatus",
+    "ConsoleNotifier",
+    "Contact",
+    "ContactResolver",
+    "DataItem",
+    "DpdpkitError",
+    "InMemoryRepository",
+    "InvalidTransition",
+    "Kit",
+    "LedgerTampered",
+    "LegalBasis",
+    "MemoryNotifier",
+    "NotFound",
+    "NoticeInvalid",
+    "Notifier",
+    "NullNotifier",
+    "Policy",
+    "PolicyError",
+    "Processor",
+    "Purpose",
+    "Registry",
+    "Repository",
+    "RequestKind",
+    "RequestStatus",
+    "RetentionRule",
+    "RetentionTrigger",
+    "Role",
+    "ScheduleStatus",
+    "SmtpNotifier",
+    "ValidationFailed",
+    "__version__",
+    "kit_from_config",
+    "load_config",
+    "sync_notice",
+]

dpdpkit/_util.py

@@ -0,0 +1,63 @@
+"""Small helpers shared by every core module. Not public API."""
+
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+import hmac
+import json
+import uuid
+from collections.abc import Callable
+from typing import Any
+
+Clock = Callable[[], dt.datetime]
+
+
+def utcnow() -> dt.datetime:
+    return dt.datetime.now(dt.timezone.utc)
+
+
+def as_utc(value: dt.datetime) -> dt.datetime:
+    """Treat naive datetimes as UTC (some databases drop tzinfo) and convert aware ones to UTC."""
+    if value.tzinfo is None:
+        return value.replace(tzinfo=dt.timezone.utc)
+    return value.astimezone(dt.timezone.utc)
+
+
+def new_id(prefix: str) -> str:
+    return f"{prefix}_{uuid.uuid4().hex}"
+
+
+def _canonical_default(value: Any) -> Any:
+    if isinstance(value, dt.datetime):
+        # Fixed format so a value read back from any database hashes identically.
+        return as_utc(value).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+    if isinstance(value, dt.date):
+        return value.isoformat()
+    if hasattr(value, "value"):  # enums
+        return value.value
+    raise TypeError(f"cannot canonicalise {type(value).__name__}")
+
+
+def canonical_json(data: Any) -> bytes:
+    """Deterministic JSON used for hashing and signing."""
+    return json.dumps(
+        data, sort_keys=True, separators=(",", ":"), ensure_ascii=False, default=_canonical_default
+    ).encode("utf-8")
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def hmac_sha256_hex(key: bytes, data: bytes) -> str:
+    return hmac.new(key, data, hashlib.sha256).hexdigest()
+
+
+def mask_address(value: str) -> str:
+    """Mask an email address or phone number for receipts and logs."""
+    if "@" in value:
+        local, _, domain = value.partition("@")
+        return f"{local[:1]}***@{domain}"
+    digits = value.strip()
+    return "*" * max(len(digits) - 4, 0) + digits[-4:]

dpdpkit/cli.py

@@ -0,0 +1,212 @@
+"""The ``dpdpkit`` command.
+
+Commands that need data (``ledger``, ``retention``, ``export``) load your kit with
+``--kit module:attribute`` or the ``DPDPKIT_KIT`` environment variable. The attribute may be a
+:class:`~dpdpkit.Kit`, an object with a ``.kit`` attribute (such as an adapter), or a zero-argument
+callable returning either.
+
+Adapters add subcommands through the ``dpdpkit.cli`` entry-point group: each entry point is a
+callable receiving the argparse sub-parsers object.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import importlib
+import json
+import os
+import sys
+from collections.abc import Sequence
+from importlib.metadata import entry_points
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .config import STARTER_CONFIG
+from .errors import DpdpkitError, LedgerTampered
+from .kit import Kit
+from .policy import Policy, available_packs
+
+
+def load_kit(spec: str | None) -> Kit:
+    spec = spec or os.environ.get("DPDPKIT_KIT")
+    if not spec or ":" not in spec:
+        raise SystemExit("error: pass --kit module:attribute (or set DPDPKIT_KIT) to load your kit")
+    module_name, _, attr = spec.partition(":")
+    sys.path.insert(0, os.getcwd())
+    obj: Any = importlib.import_module(module_name)
+    for part in attr.split("."):
+        obj = getattr(obj, part)
+    if callable(obj) and not isinstance(obj, Kit) and not hasattr(obj, "kit"):
+        obj = obj()
+    if hasattr(obj, "kit") and not isinstance(obj, Kit):
+        obj = obj.kit
+    if not isinstance(obj, Kit):
+        raise SystemExit(f"error: {spec} is not a dpdpkit Kit")
+    return obj
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    target = Path(args.dir) / "dpdpkit.yaml"
+    if target.exists() and not args.force:
+        print(f"{target} already exists (use --force to overwrite)", file=sys.stderr)
+        return 1
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(STARTER_CONFIG, encoding="utf-8")
+    print(f"wrote {target}")
+    print("next: edit purposes and notice text, then wire a repository (see your adapter's quickstart)")
+    return 0
+
+
+def _policy_from(ref: str, overlays: Sequence[str]) -> Policy:
+    return Policy.from_file(ref, overlays) if Path(ref).is_file() else Policy.load(ref, overlays)
+
+
+def _cmd_policy(args: argparse.Namespace) -> int:
+    if args.policy_command == "list":
+        for pack_id in available_packs():
+            print(pack_id)
+        return 0
+    if args.policy_command == "show":
+        pack = _policy_from(args.pack or available_packs()[-1], args.overlay)
+        print(yaml.safe_dump(pack.as_dict(), sort_keys=False, allow_unicode=True), end="")
+        return 0
+    old = _policy_from(args.old, [])
+    new = _policy_from(args.new, [])
+    changes = old.diff(new)
+    if not changes:
+        print(f"no differences between {old.id} and {new.id}")
+        return 0
+    print(f"{old.id} -> {new.id}")
+    for change in changes:
+        print(f"  {change.key}: {json.dumps(change.old)} -> {json.dumps(change.new)}")
+    return 0
+
+
+def _cmd_ledger(args: argparse.Namespace) -> int:
+    kit = load_kit(args.kit)
+    if args.ledger_command == "root":
+        print(kit.ledger.root_hash().model_dump_json(indent=2))
+        return 0
+    try:
+        result = kit.ledger.verify()
+    except LedgerTampered as exc:
+        print(f"FAILED: {exc}", file=sys.stderr)
+        return 2
+    print(
+        f"ok: {result.checked} rows verified; consent head {result.consent_head[:16]}…, "
+        f"audit head {result.audit_head[:16]}…"
+    )
+    return 0
+
+
+def _cmd_retention(args: argparse.Namespace) -> int:
+    kit = load_kit(args.kit)
+    if args.retention_command == "run":
+        run = kit.retention.run()
+        print(run.model_dump_json(indent=2))
+        return 0
+    items = kit.retention.preview(horizon=dt.timedelta(hours=args.hours))
+    if not items:
+        print(f"nothing due in the next {args.hours} hours")
+    for item in items:
+        print(f"{item.at.isoformat()}  {item.action:<5}  {item.principal}  {item.purpose}  ({item.status.value})")
+    attention = kit.retention.needs_attention()
+    if attention:
+        print(f"\n{len(attention)} schedule(s) need attention:")
+        for s in attention:
+            print(f"  {s.id}  {s.principal}  {s.purpose}: {s.attention_reason}")
+    return 0
+
+
+def _cmd_export(args: argparse.Namespace) -> int:
+    kit = load_kit(args.kit)
+    if args.evidence:
+        data = kit.export.evidence_pack()
+        out = Path(args.out or "dpdpkit-evidence.zip")
+        out.write_bytes(data)
+        print(f"wrote {out}")
+        return 0
+    if not args.principal:
+        print("error: --principal is required (or use --evidence)", file=sys.stderr)
+        return 1
+    text = (
+        kit.export.principal_html(args.principal)
+        if args.format == "html"
+        else json.dumps(kit.export.principal(args.principal), indent=2, ensure_ascii=False)
+    )
+    if args.out:
+        Path(args.out).write_text(text, encoding="utf-8")
+        print(f"wrote {args.out}")
+    else:
+        print(text)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="dpdpkit", description="dpdpkit command line")
+    parser.add_argument("--version", action="version", version=f"dpdpkit-core {_version()}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("init", help="write a starter dpdpkit.yaml")
+    p.add_argument("--dir", default=".")
+    p.add_argument("--force", action="store_true")
+    p.set_defaults(func=_cmd_init)
+
+    p = sub.add_parser("policy", help="show, list or diff policy packs")
+    psub = p.add_subparsers(dest="policy_command", required=True)
+    psub.add_parser("list")
+    show = psub.add_parser("show")
+    show.add_argument("--pack", help="pack id or file (default: newest shipped pack)")
+    show.add_argument("--overlay", action="append", default=[])
+    diff = psub.add_parser("diff")
+    diff.add_argument("old")
+    diff.add_argument("new")
+    p.set_defaults(func=_cmd_policy)
+
+    p = sub.add_parser("ledger", help="verify the hash chain or print the root hash")
+    p.add_argument("ledger_command", choices=["verify", "root"])
+    p.add_argument("--kit")
+    p.set_defaults(func=_cmd_ledger)
+
+    p = sub.add_parser("retention", help="preview or run erasure schedules")
+    p.add_argument("retention_command", choices=["preview", "run"])
+    p.add_argument("--hours", type=int, default=168)
+    p.add_argument("--kit")
+    p.set_defaults(func=_cmd_retention)
+
+    p = sub.add_parser("export", help="export a principal's data, or an evidence pack")
+    p.add_argument("--principal")
+    p.add_argument("--evidence", action="store_true")
+    p.add_argument("--format", choices=["json", "html"], default="json")
+    p.add_argument("--out")
+    p.add_argument("--kit")
+    p.set_defaults(func=_cmd_export)
+
+    for ep in entry_points(group="dpdpkit.cli"):
+        try:
+            ep.load()(sub)
+        except Exception as exc:  # a broken plugin must not break the core CLI
+            print(f"warning: dpdpkit CLI plugin {ep.name} failed to load: {exc}", file=sys.stderr)
+    return parser
+
+
+def _version() -> str:
+    from . import __version__
+
+    return __version__
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return int(args.func(args))
+    except DpdpkitError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

dpdpkit/config.py

@@ -0,0 +1,135 @@
+"""``dpdpkit.yaml``: purposes, notice text, contact details and policy selection.
+
+Adapters and the server build a :class:`~dpdpkit.Kit` from this file and call :func:`sync_notice`
+at start-up, which publishes a new notice version only when the configured text changed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .errors import ConfigError, NotFound
+from .kit import Kit
+from .models import Notice, NoticeContent
+from .notices import content_hash
+from .registry import Registry
+from .repository import Repository
+
+STARTER_CONFIG = """\
+# dpdpkit configuration.
+# Purposes, notice wording and retention periods are decisions for you and your counsel.
+# dpdpkit records and enforces what you configure; it does not decide what is lawful.
+policy: dpdp-rules-2025.v1
+overlays: []
+
+contact:
+  name: Example Pvt Ltd
+  email: privacy@example.in
+  rights_url: https://example.in/privacy/rights
+
+data_items:
+  - {id: email, name: Email address}
+  - {id: phone, name: Mobile number}
+  - {id: name, name: Full name}
+  - {id: order_history, name: Order history}
+
+processors:
+  - {id: mailer, name: Email delivery provider, country: IN}
+
+purposes:
+  - id: account
+    title: Create and run your account
+    description: We use these details to sign you in and provide the service.
+    data_items: [email, phone, name, order_history]
+    required: true
+    retention: {trigger: last_activity, period_days: 1095}
+  - id: marketing
+    title: Send you offers
+    description: Occasional emails about products and discounts.
+    data_items: [email]
+    processors: [mailer]
+    retention: {trigger: withdrawal, period_days: 0}
+
+notice:
+  title: How we use your personal data
+  body: Choose what you agree to. You can change your choices at any time.
+  links:
+    withdraw: https://example.in/privacy/preferences
+    rights: https://example.in/privacy/rights
+    board_complaint: https://example.in/privacy/board-complaint   # replace with the Board's complaint page
+  translations:
+    hi:
+      title: हम आपके व्यक्तिगत डेटा का उपयोग कैसे करते हैं
+      body: चुनें कि आप किस बात से सहमत हैं। आप कभी भी अपनी पसंद बदल सकते हैं।
+      purposes:
+        account: {title: आपका खाता बनाना और चलाना}
+        marketing: {title: आपको ऑफ़र भेजना}
+"""
+
+
+def load_config(path: str | Path) -> dict[str, Any]:
+    try:
+        data = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise ConfigError(f"cannot read {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path} must contain a mapping")
+    if "policy" not in data:
+        raise ConfigError(f"{path} must name a policy pack (policy: dpdp-rules-2025.v1)")
+    return data
+
+
+def kit_from_config(config: Mapping[str, Any] | str | Path, repository: Repository, **kwargs: Any) -> Kit:
+    """Build a :class:`Kit` from a config mapping or file. ``kwargs`` override or extend Kit arguments."""
+    cfg = load_config(config) if isinstance(config, (str, Path)) else dict(config)
+    tenant_id = str(kwargs.pop("tenant_id", cfg.get("tenant_id", "default")))
+    return Kit(
+        repository=repository,
+        policy=str(cfg["policy"]),
+        overlays=list(cfg.get("overlays") or []),
+        registry=kwargs.pop("registry", None) or Registry.from_config(cfg, tenant_id),
+        contact=kwargs.pop("contact", None) or cfg.get("contact") or {},
+        tenant_id=tenant_id,
+        **kwargs,
+    )
+
+
+def notice_translations(kit: Kit, notice_cfg: Mapping[str, Any]) -> dict[str, NoticeContent]:
+    try:
+        links = dict(notice_cfg["links"])
+        title = str(notice_cfg["title"])
+    except KeyError as exc:
+        raise ConfigError(f"notice config is missing {exc}") from exc
+    body = str(notice_cfg.get("body", ""))
+    default = kit.policy.default_language
+    out = {default: kit.notices.build_content(title=title, body=body, links=links)}
+    for locale, text in (notice_cfg.get("translations") or {}).items():
+        out[str(locale)] = kit.notices.build_content(
+            title=str(text.get("title", title)),
+            body=str(text.get("body", body)),
+            links={**links, **(text.get("links") or {})},
+            purposes=text.get("purposes") or {},
+        )
+    return out
+
+
+def sync_notice(kit: Kit, config: Mapping[str, Any], *, actor: str = "config") -> list[Notice] | None:
+    """Publish the configured notice if it differs from the current one. Returns the new notices or None."""
+    notice_cfg = config.get("notice")
+    if not notice_cfg:
+        return None
+    wanted = notice_translations(kit, notice_cfg)
+    try:
+        current = kit.notices.current()
+        existing = {
+            n.locale: n.content_hash for n in kit.repository.list_notices(kit.tenant_id, version=current.version)
+        }
+    except NotFound:
+        existing = {}
+    if existing == {loc: content_hash(c) for loc, c in wanted.items()}:
+        return None
+    return kit.notices.publish(wanted, actor=actor)