atherdlp 0.0.2__tar.gz

atherdlp-0.0.2/.gitignore

@@ -0,0 +1,31 @@
+# Python caches / artifacts
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Virtualenvs
+.venv/
+venv/
+ENV/
+env/
+
+# Local env/secrets
+.env
+.env.*
+!.env.example
+
+# Logs
+*.log
+
+# Build output
+dist/
+build/
+*.egg-info/
+
+# OS
+.DS_Store

atherdlp-0.0.2/LICENSE

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

atherdlp-0.0.2/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: atherdlp
+Version: 0.0.2
+Summary: Developer-first DLP HTTP interceptor (Stage 1)
+Project-URL: Homepage, https://github.com/AetherDLP/AtherDLP-sdk
+Project-URL: Repository, https://github.com/AetherDLP/AtherDLP-sdk
+Project-URL: Issues, https://github.com/AetherDLP/AtherDLP-sdk/issues
+Author-email: Subham Singh Chauhan <subhamchauhan1100@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dlp,httpx,interceptor,observability,security,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: respx>=0.21; extra == 'test'
+Description-Content-Type: text/markdown
+
+# AtherDLP (Python) — Stage 1 HTTP Interceptor
+
+Stage 1 intercepts outbound HTTP requests, classifies the destination (O(1) registry lookup), attaches a trace context, and emits a structured payload to a handler.
+
+## Install (dev)
+
+```bash
+cd AtherDLP-sdk/python
+python -m pip install -e ".[test]"
+```
+
+## Usage
+
+```python
+import httpx
+import atherdlp
+
+def handler(payload: dict) -> None:
+    print(payload)
+
+atherdlp.set_handler(handler)
+atherdlp.install()
+
+httpx.get("https://api.openai.com/v1/models", headers={"authorization": "Bearer x"})
+
+atherdlp.uninstall()
+```
+
+### Tracing
+
+- If the request includes a **correlation header** (e.g. **`X-Correlation-Id`**), it is **propagated automatically** (safe values only: **ASCII alphanumeric + `-`, 1–64 chars**).
+- If **not** present or invalid, AtherDLP **generates its own** trace id (`trace.trace_id` in the payload).
+- **Ather-specific** tracing is **always** added on the outbound call via **`x-ather-trace-id`** (and **`x-ather-span-id`**).
+
+More detail: **`docs/SDK.md`** → *Trace And Recursion Guards*.
+
+```python
+httpx.post(url, headers={"X-Correlation-Id": "my-route-8842"})
+```
+
+## Output payload
+
+```json
+{
+  "request": { "method": "...", "url": "...", "headers": { }, "body": null },
+  "classification": { "kind": "llm|http.out|unknown", "vendor": "...", "sensitivity": "..." },
+  "trace": { "trace_id": "...", "span_id": "...", "parent_span_id": null }
+}
+```

atherdlp-0.0.2/README.md

@@ -0,0 +1,49 @@
+# AtherDLP (Python) — Stage 1 HTTP Interceptor
+
+Stage 1 intercepts outbound HTTP requests, classifies the destination (O(1) registry lookup), attaches a trace context, and emits a structured payload to a handler.
+
+## Install (dev)
+
+```bash
+cd AtherDLP-sdk/python
+python -m pip install -e ".[test]"
+```
+
+## Usage
+
+```python
+import httpx
+import atherdlp
+
+def handler(payload: dict) -> None:
+    print(payload)
+
+atherdlp.set_handler(handler)
+atherdlp.install()
+
+httpx.get("https://api.openai.com/v1/models", headers={"authorization": "Bearer x"})
+
+atherdlp.uninstall()
+```
+
+### Tracing
+
+- If the request includes a **correlation header** (e.g. **`X-Correlation-Id`**), it is **propagated automatically** (safe values only: **ASCII alphanumeric + `-`, 1–64 chars**).
+- If **not** present or invalid, AtherDLP **generates its own** trace id (`trace.trace_id` in the payload).
+- **Ather-specific** tracing is **always** added on the outbound call via **`x-ather-trace-id`** (and **`x-ather-span-id`**).
+
+More detail: **`docs/SDK.md`** → *Trace And Recursion Guards*.
+
+```python
+httpx.post(url, headers={"X-Correlation-Id": "my-route-8842"})
+```
+
+## Output payload
+
+```json
+{
+  "request": { "method": "...", "url": "...", "headers": { }, "body": null },
+  "classification": { "kind": "llm|http.out|unknown", "vendor": "...", "sensitivity": "..." },
+  "trace": { "trace_id": "...", "span_id": "...", "parent_span_id": null }
+}
+```

atherdlp-0.0.2/atherdlp/__init__.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Callable
+
+from atherdlp.config import configure, get_config
+from atherdlp.interceptor.httpx_hook import install_httpx, uninstall_httpx
+
+_handler: Callable[[dict], None] | None = None
+
+
+def set_handler(handler: Callable[[dict], None] | None) -> None:
+    """
+    Set the callback that receives intercepted payloads.
+
+    The handler must be fail-safe; exceptions are swallowed by the interceptor.
+    """
+
+    global _handler
+    _handler = handler
+
+
+def _get_handler() -> Callable[[dict], None]:
+    h = _handler
+    if h is None:
+        return lambda _payload: None
+    return h
+
+
+def install() -> None:
+    install_httpx(_get_handler())
+
+
+def uninstall() -> None:
+    uninstall_httpx()

atherdlp-0.0.2/atherdlp/classifier/__init__.py

@@ -0,0 +1,4 @@
+from atherdlp.classifier.classify import classify_destination
+from atherdlp.classifier.providers import PROVIDERS, register_provider
+
+__all__ = ["PROVIDERS", "register_provider", "classify_destination"]

atherdlp-0.0.2/atherdlp/classifier/classify.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+from atherdlp.classifier.providers import PROVIDERS
+
+
+def classify_destination(url: str) -> dict:
+    host = (urlparse(url).hostname or "").lower()
+    meta = PROVIDERS.get(host)
+    if meta is None:
+        return {"kind": "unknown", "vendor": None}
+    return dict(meta)

atherdlp-0.0.2/atherdlp/classifier/providers.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Mapping
+
+
+PROVIDERS: dict[str, dict] = {
+    "api.openai.com": {"kind": "llm", "vendor": "openai"},
+    "api.anthropic.com": {"kind": "llm", "vendor": "anthropic"},
+    "generativelanguage.googleapis.com": {"kind": "llm", "vendor": "google"},
+    "api.cohere.ai": {"kind": "llm", "vendor": "cohere"},
+    "api.mistral.ai": {"kind": "llm", "vendor": "mistral"},
+    "api.stripe.com": {"kind": "http.out", "vendor": "stripe", "sensitivity": "pci"},
+    "api.github.com": {"kind": "http.out", "vendor": "github"},
+}
+
+
+def register_provider(host: str, meta: Mapping) -> None:
+    PROVIDERS[host.lower()] = dict(meta)

atherdlp-0.0.2/atherdlp/config.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SDKConfig:
+    endpoint: str | None = None
+    api_key: str | None = None
+    timeout_s: float = 0.2
+    enabled: bool = True
+    # Max backend emit tasks accepted at once (queued in the executor + running).
+    # When saturated, new emits are dropped (fail-open). Use 0 for no limit (not recommended under load).
+    max_pending_backend_emits: int = 128
+
+
+_config = SDKConfig()
+
+
+def configure(
+    *,
+    endpoint: str | None = None,
+    api_key: str | None = None,
+    timeout_s: float = 0.2,
+    enabled: bool = True,
+    max_pending_backend_emits: int = 128,
+) -> None:
+    global _config
+    _config = SDKConfig(
+        endpoint=endpoint,
+        api_key=api_key,
+        timeout_s=timeout_s,
+        enabled=enabled,
+        max_pending_backend_emits=max_pending_backend_emits,
+    )
+
+
+def get_config() -> SDKConfig:
+    return _config
+

atherdlp-0.0.2/atherdlp/context/__init__.py

@@ -0,0 +1,3 @@
+from atherdlp.context.trace import TraceContext, new_span_id, new_trace, new_trace_id
+
+__all__ = ["TraceContext", "new_trace_id", "new_span_id", "new_trace"]

atherdlp-0.0.2/atherdlp/context/trace.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import secrets
+from dataclasses import asdict, dataclass
+
+
+@dataclass(frozen=True)
+class TraceContext:
+    trace_id: str
+    span_id: str
+    parent_span_id: str | None = None
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def new_trace_id() -> str:
+    # 32 hex chars (W3C trace-id compatible shape)
+    return secrets.token_hex(16)
+
+
+def new_span_id() -> str:
+    # 16 hex chars (W3C span-id compatible shape)
+    return secrets.token_hex(8)
+
+
+def new_trace(*, parent_span_id: str | None = None) -> TraceContext:
+    return TraceContext(trace_id=new_trace_id(), span_id=new_span_id(), parent_span_id=parent_span_id)

atherdlp-0.0.2/atherdlp/interceptor/__init__.py

@@ -0,0 +1,4 @@
+from atherdlp.interceptor.base import InterceptedPayload, PayloadHandler
+from atherdlp.interceptor.httpx_hook import install_httpx, uninstall_httpx
+
+__all__ = ["InterceptedPayload", "PayloadHandler", "install_httpx", "uninstall_httpx"]

atherdlp-0.0.2/atherdlp/interceptor/base.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Protocol
+
+
+class PayloadHandler(Protocol):
+    def __call__(self, payload: dict) -> None: ...
+
+
+@dataclass(frozen=True)
+class InterceptedPayload:
+    request: dict
+    classification: dict
+    trace: dict
+
+    def to_dict(self) -> dict:
+        return asdict(self)

atherdlp-0.0.2/atherdlp/interceptor/httpx_hook.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from atherdlp.classifier.classify import classify_destination
+from atherdlp.context.trace import new_trace
+from atherdlp.config import get_config
+from atherdlp.interceptor.base import PayloadHandler
+from atherdlp.limits import get_sdk_interceptor_bytes_limits
+from atherdlp.transport.sender import send_to_backend
+
+from email.parser import BytesParser
+from email.policy import default
+
+@dataclass
+class _State:
+    installed: bool = False
+    handler: PayloadHandler | None = None
+    orig_client_init: Any | None = None
+    orig_async_client_init: Any | None = None
+
+
+_state = _State()
+
+
+def install_httpx(handler: PayloadHandler) -> None:
+    if _state.installed:
+        _state.handler = handler
+        return
+
+    _state.handler = handler
+    _state.orig_client_init = httpx.Client.__init__
+    _state.orig_async_client_init = httpx.AsyncClient.__init__
+
+    def _client_init(self: httpx.Client, *args: Any, **kwargs: Any) -> None:
+        assert _state.orig_client_init is not None
+        _state.orig_client_init(self, *args, **kwargs)
+        if getattr(self, "_transport", None) is not None:
+            self._transport = _AtherTransport(self._transport)
+        if getattr(self, "_mounts", None):
+            self._mounts = {k: _AtherTransport(v) for k, v in self._mounts.items()}
+
+    def _async_client_init(self: httpx.AsyncClient, *args: Any, **kwargs: Any) -> None:
+        assert _state.orig_async_client_init is not None
+        _state.orig_async_client_init(self, *args, **kwargs)
+        if getattr(self, "_transport", None) is not None:
+            self._transport = _AtherAsyncTransport(self._transport)
+        if getattr(self, "_mounts", None):
+            self._mounts = {k: _AtherAsyncTransport(v) for k, v in self._mounts.items()}
+
+    httpx.Client.__init__ = _client_init  # type: ignore[assignment]
+    httpx.AsyncClient.__init__ = _async_client_init  # type: ignore[assignment]
+    _state.installed = True
+
+
+def uninstall_httpx() -> None:
+    global _state
+    if not _state.installed:
+        return
+    if _state.orig_client_init is not None:
+        httpx.Client.__init__ = _state.orig_client_init  # type: ignore[assignment]
+    if _state.orig_async_client_init is not None:
+        httpx.AsyncClient.__init__ = _state.orig_async_client_init  # type: ignore[assignment]
+    _state = _State()  # reset
+
+
+class _AtherTransport(httpx.BaseTransport):
+    def __init__(self, inner: httpx.BaseTransport):
+        self._inner = inner
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        _emit(request)
+        return self._inner.handle_request(request)
+
+
+class _AtherAsyncTransport(httpx.AsyncBaseTransport):
+    def __init__(self, inner: httpx.AsyncBaseTransport):
+        self._inner = inner
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        _emit(request)
+        return await self._inner.handle_async_request(request)
+
+
+def _emit(request: httpx.Request) -> None:
+    # Never intercept SDK-internal backend calls (prevents recursion).
+    if request.headers.get("x-ather-internal") == "1":
+        return
+
+    # Also skip interception when the destination is the configured backend endpoint.
+    cfg = get_config()
+    if cfg.endpoint:
+        try:
+            if str(request.url) == str(cfg.endpoint):
+                return
+        except Exception:
+            pass
+
+    trace = new_trace().to_dict()
+    # Propagate trace to the upstream destination (best-effort).
+    try:
+        request.headers["x-ather-trace-id"] = trace["trace_id"]
+        request.headers["x-ather-span-id"] = trace["span_id"]
+    except Exception:
+        pass
+
+    classification = classify_destination(str(request.url))
+
+    payload = {
+        "request": {
+            "method": request.method,
+            "url": str(request.url),
+            "headers": dict(request.headers),
+            "body": _safe_body(request),
+        },
+        "classification": classification,
+        "trace": trace,
+    }
+
+    # Best-effort delivery to backend (non-blocking, fail-open).
+    send_to_backend(payload)
+
+    handler = _state.handler
+    if handler is None:
+        return
+    try:
+        handler(payload)
+    except Exception:
+        # fail-open: never break the host app
+        return
+
+
+def _safe_body(request: httpx.Request) -> Any:
+    try:
+        raw = request.content or b""
+    except httpx.RequestNotRead:
+        # Multipart/form uploads are streamed by default. Reading here should
+        # materialize the bytes and keep request semantics intact.
+        raw = request.read() or b""
+    if not raw:
+        return None
+
+    ctype = request.headers.get("content-type", "")
+
+    # MULTIPART (files/form fields)
+    if "multipart/form-data" in ctype:
+        return _extract_multipart(raw, ctype)
+
+    max_non, _, sample_b = get_sdk_interceptor_bytes_limits()
+    # LARGE BODY → SAMPLE
+    if len(raw) > max_non:
+        return _sample_bytes(raw, size=len(raw), sample_slice_bytes=sample_b)
+
+    # JSON
+    if "application/json" in ctype:
+        try:
+            return json.loads(raw)
+        except Exception:
+            pass
+
+    # TEXT
+    try:
+        return raw.decode("utf-8")
+    except Exception:
+        return {"_binary": True, "size": len(raw)}
+   
+
+
+
+def _sample_bytes(raw: bytes, *, size: int, sample_slice_bytes: int) -> dict:
+    sb = max(1, sample_slice_bytes)
+    start = raw[:sb]
+    mid_start = max(0, size // 2 - sb // 2)
+    middle = raw[mid_start : mid_start + sb]
+    end = raw[-sb:] if size >= sb else raw
+
+    def _to_text(chunk: bytes) -> str:
+        try:
+            return chunk.decode("utf-8", errors="replace")
+        except Exception:
+            return base64.b64encode(chunk).decode("ascii")
+
+    return {"_sampled": True, "size": size, "samples": [_to_text(start), _to_text(middle), _to_text(end)]}
+
+    
+def _extract_multipart(raw: bytes, content_type: str):
+    _, max_inline, sample_b = get_sdk_interceptor_bytes_limits()
+    msg = BytesParser(policy=default).parsebytes(
+        b"Content-Type: " + content_type.encode() + b"\n\n" + raw
+    )
+
+    files = []
+    fields = []
+
+    for part in msg.iter_parts():
+        content = part.get_payload(decode=True) or b""
+        # get the filename from the part If this exists → it's a file
+        filename = part.get_filename()
+
+        if filename:
+            size = len(content)
+            if size > max_inline:
+                sampled: Any = _sample_bytes(
+                    content, size=size, sample_slice_bytes=sample_b
+                )
+            else:
+                try:
+                    sampled = content.decode("utf-8", errors="replace")
+                except Exception:
+                    sampled = {"_binary": True, "size": size}
+
+            files.append({
+                "filename": filename,
+                "content": sampled,
+                "size": size,
+                "content_type": part.get_content_type(),
+            })
+
+        else:
+            fields.append({
+                "name": part.get_param("name", header="content-disposition"),
+                "value": content.decode("utf-8", errors="replace") if content else None
+            })
+
+    return {
+        "files": files,
+        "fields": fields
+    }
+    

atherdlp-0.0.2/atherdlp/limits.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+
+# Default values must match AtherDLP-infra/.env.example (canonical source in repo).
+
+
+def _int_env(name: str, default: int) -> int:
+    raw = os.environ.get(name)
+    if raw is None or str(raw).strip() == "":
+        return default
+    try:
+        return int(str(raw).strip(), 10)
+    except (TypeError, ValueError):
+        return default
+
+
+@lru_cache(maxsize=1)
+def get_sdk_interceptor_bytes_limits() -> tuple[int, int, int]:
+    """
+    (max_non_multipart, max_file_inline, sample_slice).
+
+    Set in process env, typically from AtherDLP-infra/.env:
+    ATHERDLP_SDK_MAX_NON_MULTIPART_BODY_BYTES
+    ATHERDLP_SDK_MAX_FILE_INLINE_BYTES
+    ATHERDLP_SDK_SAMPLE_SLICE_BYTES
+    """
+    return (
+        _int_env("ATHERDLP_SDK_MAX_NON_MULTIPART_BODY_BYTES", 2 * 1024 * 1024),
+        _int_env("ATHERDLP_SDK_MAX_FILE_INLINE_BYTES", 256 * 1024),
+        _int_env("ATHERDLP_SDK_SAMPLE_SLICE_BYTES", 16 * 1024),
+    )

atherdlp-0.0.2/atherdlp/transport/__init__.py

@@ -0,0 +1,3 @@
+from atherdlp.transport.sender import send_to_backend
+
+__all__ = ["send_to_backend"]

atherdlp-0.0.2/atherdlp/transport/sender.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import json
+import logging
+import re
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+
+import httpx
+
+from atherdlp.config import get_config
+
+_log = logging.getLogger("atherdlp")
+
+# Match backend correlation rules (shared.correlation.SAFE_CID): alnum + hyphen, max 64.
+_SAFE_CORRELATION_ID = re.compile(r"^[a-zA-Z0-9\-]{1,64}$")
+
+_executor = ThreadPoolExecutor(max_workers=4, thread_name_prefix="atherdlp")
+_emit_lock = threading.Lock()
+_pending_backend_emits = 0
+
+
+def _first_request_header(hdrs: Any, canon_name_lc: str) -> str | None:
+    """Case-insensitive first value from payload snapshot headers."""
+    if not isinstance(hdrs, dict):
+        return None
+    for k, val in hdrs.items():
+        if str(k).lower() != canon_name_lc:
+            continue
+        if val is None:
+            continue
+        s = str(val).strip()
+        if s:
+            return s
+    return None
+
+
+def _correlation_id_for_backend_header(payload: dict[str, Any], trace_id: Any) -> str | None:
+    incoming = _first_request_header(
+        (payload.get("request") or {}).get("headers"),
+        "x-correlation-id",
+    )
+    if incoming and _SAFE_CORRELATION_ID.match(incoming):
+        return incoming
+    tid = str(trace_id).strip() if trace_id is not None and str(trace_id).strip() else None
+    if tid and _SAFE_CORRELATION_ID.match(tid):
+        return tid
+    return None
+
+
+def send_to_backend(payload: dict[str, Any]) -> None:
+    """
+    Best-effort, fail-open delivery of intercepted payloads.
+    Non-blocking by design: dispatches in a thread and returns immediately.
+    """
+
+    cfg = get_config()
+    if not cfg.enabled or not cfg.endpoint:
+        return
+
+    trace = payload.get("trace") or {}
+    trace_id = trace.get("trace_id")
+    span_id = trace.get("span_id")
+
+    headers: dict[str, str] = {"content-type": "application/json"}
+    # Prevent the SDK from intercepting its own backend calls.
+    headers["x-ather-internal"] = "1"
+    if cfg.api_key:
+        # Authentication to the backend
+        headers["x-api-key"] = cfg.api_key
+    if trace_id:
+        headers["x-ather-trace-id"] = str(trace_id)
+    cid = _correlation_id_for_backend_header(payload, trace_id)
+    if cid:
+        headers["X-Correlation-Id"] = cid
+    if span_id:
+        headers["x-ather-span-id"] = str(span_id)
+
+    limit = cfg.max_pending_backend_emits
+
+    global _pending_backend_emits
+
+    def _release_pending() -> None:
+        global _pending_backend_emits
+        if limit <= 0:
+            return
+        with _emit_lock:
+            _pending_backend_emits -= 1
+
+    if limit > 0:
+        with _emit_lock:
+            if _pending_backend_emits >= limit:
+                _log.debug(
+                    "backend emit backlog saturated; dropping (%d/%d pending)",
+                    _pending_backend_emits,
+                    limit,
+                )
+                return
+            _pending_backend_emits += 1
+
+    def _do_send() -> None:
+        try:
+            body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+            # Create a short-lived client per send to avoid shared state issues.
+            with httpx.Client(timeout=cfg.timeout_s) as client:
+                client.post(cfg.endpoint, content=body, headers=headers)
+        except Exception as e:  # fail-open
+            _log.debug("backend emit failed: %s", e)
+        finally:
+            _release_pending()
+
+    try:
+        _executor.submit(_do_send)
+    except Exception as e:  # fail-open
+        if limit > 0:
+            with _emit_lock:
+                _pending_backend_emits -= 1
+        _log.debug("backend emit submit failed: %s", e)

atherdlp-0.0.2/examples/demo.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import httpx
+
+import atherdlp
+
+
+def main() -> None:
+    atherdlp.configure(endpoint="http://localhost:8473/events/http", api_key="dev")
+    atherdlp.install()
+    try:
+        # The destination doesn't need to exist for the interceptor to emit.
+        # Use any request that contains a value your SIT/policy can match.
+        httpx.post(
+            "https://api.openai.com/v1/chat/completions",
+            json={"secret": "sk-AAAA1111BBBB2222"},
+            timeout=2.0,
+        )
+    except Exception:
+        # Demo is about emitting events; ignore destination failures.
+        pass
+    finally:
+        atherdlp.uninstall()
+
+
+if __name__ == "__main__":
+    main()
+

atherdlp-0.0.2/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "atherdlp"
+version = "0.0.2"
+description = "Developer-first DLP HTTP interceptor (Stage 1)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Subham Singh Chauhan", email = "subhamchauhan1100@gmail.com" },
+]
+keywords = ["dlp", "security", "httpx", "interceptor", "observability", "tracing"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Topic :: Internet :: WWW/HTTP",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/AetherDLP/AtherDLP-sdk"
+Repository = "https://github.com/AetherDLP/AtherDLP-sdk"
+Issues = "https://github.com/AetherDLP/AtherDLP-sdk/issues"
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8",
+  "pytest-asyncio>=0.24",
+  "respx>=0.21",
+]
+
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["atherdlp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["atherdlp", "tests", "examples", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

atherdlp-0.0.2/tests/test_backend_emit.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import threading
+
+import httpx
+import pytest
+import respx
+
+import atherdlp
+
+
+def test_backend_emit_non_blocking_and_trace_headers() -> None:
+    seen: list[dict] = []
+    backend_called = threading.Event()
+    backend_headers: dict[str, str] = {}
+
+    def handler(payload: dict) -> None:
+        seen.append(payload)
+
+    atherdlp.set_handler(handler)
+    atherdlp.configure(endpoint="https://backend.local/events/http", api_key="dev", timeout_s=0.2)
+    atherdlp.install()
+
+    with respx.mock(assert_all_called=False) as router:
+        router.post("https://backend.local/events/http").mock(
+            side_effect=lambda request: _mark_backend_call(request, backend_called, backend_headers)
+        )
+        router.get("https://httpbin.org/get").respond(200, json={"ok": True})
+
+        r = httpx.get("https://httpbin.org/get")
+        assert r.status_code == 200
+
+        assert len(seen) == 1
+        trace_id = seen[0]["trace"]["trace_id"]
+
+        # Sender is async; wait briefly for delivery.
+        assert backend_called.wait(1.0) is True
+        assert backend_headers.get("x-ather-trace-id") == trace_id
+        assert backend_headers.get("x-correlation-id") == trace_id
+
+    atherdlp.uninstall()
+
+
+def test_backend_emit_prefers_safe_inbound_x_correlation_id() -> None:
+    seen: list[dict] = []
+    backend_called = threading.Event()
+    backend_headers: dict[str, str] = {}
+
+    def handler(payload: dict) -> None:
+        seen.append(payload)
+
+    atherdlp.set_handler(handler)
+    atherdlp.configure(endpoint="https://backend.local/events/http", api_key="dev", timeout_s=0.2)
+    atherdlp.install()
+
+    inbound_cid = "acme-upstream-001"
+
+    with respx.mock(assert_all_called=False) as router:
+        router.post("https://backend.local/events/http").mock(
+            side_effect=lambda request: _mark_backend_call(request, backend_called, backend_headers)
+        )
+        router.get("https://httpbin.org/get").respond(200, json={"ok": True})
+
+        r = httpx.get(
+            "https://httpbin.org/get",
+            headers={"X-Correlation-Id": inbound_cid},
+        )
+        assert r.status_code == 200
+
+        assert len(seen) == 1
+        trace_id = seen[0]["trace"]["trace_id"]
+        assert trace_id != inbound_cid
+
+        assert backend_called.wait(1.0) is True
+        assert backend_headers.get("x-correlation-id") == inbound_cid
+        assert backend_headers.get("x-ather-trace-id") == trace_id
+
+    atherdlp.uninstall()
+
+
+def test_backend_emit_falls_back_when_inbound_x_correlation_id_unsafe() -> None:
+    seen: list[dict] = []
+    backend_called = threading.Event()
+    backend_headers: dict[str, str] = {}
+
+    def handler(payload: dict) -> None:
+        seen.append(payload)
+
+    atherdlp.set_handler(handler)
+    atherdlp.configure(endpoint="https://backend.local/events/http", api_key="dev", timeout_s=0.2)
+    atherdlp.install()
+
+    bad_cid = "x" * 65
+
+    with respx.mock(assert_all_called=False) as router:
+        router.post("https://backend.local/events/http").mock(
+            side_effect=lambda request: _mark_backend_call(request, backend_called, backend_headers)
+        )
+        router.get("https://httpbin.org/get").respond(200, json={"ok": True})
+
+        r = httpx.get("https://httpbin.org/get", headers={"X-Correlation-Id": bad_cid})
+        assert r.status_code == 200
+
+        assert len(seen) == 1
+        trace_id = seen[0]["trace"]["trace_id"]
+
+        assert backend_called.wait(1.0) is True
+        assert backend_headers.get("x-correlation-id") == trace_id
+        assert bad_cid not in backend_headers.values()
+
+    atherdlp.uninstall()
+
+
+def test_upstream_httpx_request_includes_propagated_trace_headers() -> None:
+    """Headers x-ather-trace-id / x-ather-span-id on the real outbound upstream request."""
+
+    upstream_headers: dict[str, str] = {}
+
+    def capture_upstream(request: httpx.Request) -> httpx.Response:
+        upstream_headers.clear()
+        upstream_headers.update({k.lower(): v for k, v in request.headers.items()})
+        return httpx.Response(200, json={"ok": True})
+
+    seen: list[dict] = []
+
+    def handler(payload: dict) -> None:
+        seen.append(payload)
+
+    atherdlp.set_handler(handler)
+    atherdlp.configure(endpoint="https://backend.local/events/http", api_key="dev", timeout_s=0.2)
+    atherdlp.install()
+
+    with respx.mock(assert_all_called=False) as router:
+        router.post("https://backend.local/events/http").respond(200, json={"ok": True})
+        router.get("https://upstream.example/up").mock(side_effect=capture_upstream)
+
+        r = httpx.get("https://upstream.example/up")
+        assert r.status_code == 200
+
+    assert len(seen) == 1
+    trace = seen[0]["trace"]
+    assert upstream_headers.get("x-ather-trace-id") == trace["trace_id"]
+    assert upstream_headers.get("x-ather-span-id") == trace["span_id"]
+
+    atherdlp.uninstall()
+
+
+@pytest.mark.asyncio
+async def test_upstream_async_httpx_request_includes_propagated_trace_headers() -> None:
+    """Same as sync test: _AtherAsyncTransport injects trace headers on the upstream request."""
+
+    upstream_headers: dict[str, str] = {}
+
+    def capture_upstream(request: httpx.Request) -> httpx.Response:
+        upstream_headers.clear()
+        upstream_headers.update({k.lower(): v for k, v in request.headers.items()})
+        return httpx.Response(200, json={"ok": True})
+
+    seen: list[dict] = []
+
+    def handler(payload: dict) -> None:
+        seen.append(payload)
+
+    atherdlp.set_handler(handler)
+    atherdlp.configure(endpoint="https://backend.local/events/http", api_key="dev", timeout_s=0.2)
+    atherdlp.install()
+
+    try:
+        with respx.mock(assert_all_called=False) as router:
+            router.post("https://backend.local/events/http").respond(200, json={"ok": True})
+            router.get("https://upstream.example/async-up").mock(side_effect=capture_upstream)
+
+            async with httpx.AsyncClient() as client:
+                r = await client.get("https://upstream.example/async-up")
+
+        assert r.status_code == 200
+        assert len(seen) == 1
+        trace = seen[0]["trace"]
+        assert upstream_headers.get("x-ather-trace-id") == trace["trace_id"]
+        assert upstream_headers.get("x-ather-span-id") == trace["span_id"]
+    finally:
+        atherdlp.uninstall()
+
+
+def test_backend_emit_fail_open_on_timeout() -> None:
+    atherdlp.configure(endpoint="https://backend.local/events/http", api_key="dev", timeout_s=0.001)
+    atherdlp.install()
+
+    with respx.mock(assert_all_called=False) as router:
+        router.post("https://backend.local/events/http").mock(side_effect=httpx.ReadTimeout("timeout"))
+        router.get("https://httpbin.org/get").respond(200, json={"ok": True})
+
+        r = httpx.get("https://httpbin.org/get")
+        assert r.status_code == 200
+
+    atherdlp.uninstall()
+
+
+def _mark_backend_call(request: httpx.Request, ev: threading.Event, out: dict[str, str]) -> httpx.Response:
+    out.update({k.lower(): v for k, v in request.headers.items()})
+    ev.set()
+    return httpx.Response(200, json={"ok": True})
+

atherdlp-0.0.2/tests/test_classifier.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from atherdlp.classifier.classify import classify_destination
+
+
+def test_known_llm_host() -> None:
+    out = classify_destination("https://api.openai.com/v1/models")
+    assert out["kind"] == "llm"
+    assert out["vendor"] == "openai"
+
+
+def test_unknown_host() -> None:
+    out = classify_destination("https://example.com/path")
+    assert out["kind"] == "unknown"
+    assert out["vendor"] is None
+
+
+def test_case_insensitive() -> None:
+    out = classify_destination("https://API.OPENAI.COM/v1/models")
+    assert out["kind"] == "llm"
+
+
+def test_url_with_port() -> None:
+    out = classify_destination("https://api.openai.com:443/v1/models")
+    assert out["kind"] == "llm"
+

atherdlp-0.0.2/tests/test_context.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import re
+
+from atherdlp.context.trace import new_span_id, new_trace, new_trace_id
+
+
+HEX32 = re.compile(r"^[0-9a-f]{32}$")
+HEX16 = re.compile(r"^[0-9a-f]{16}$")
+
+
+def test_trace_id_format() -> None:
+    tid = new_trace_id()
+    assert HEX32.match(tid)
+
+
+def test_span_id_format() -> None:
+    sid = new_span_id()
+    assert HEX16.match(sid)
+
+
+def test_new_trace_creates_ids() -> None:
+    t1 = new_trace()
+    t2 = new_trace()
+    assert HEX32.match(t1.trace_id)
+    assert HEX16.match(t1.span_id)
+    assert t1.parent_span_id is None
+    assert t1.trace_id != t2.trace_id
+    assert t1.span_id != t2.span_id
+

atherdlp-0.0.2/tests/test_httpbin_basic.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import httpx
+import respx
+
+import atherdlp
+from atherdlp.classifier.providers import register_provider
+
+
+def test_httpbin_basic_intercept_and_classify() -> None:
+    register_provider("httpbin.org", {"kind": "test", "vendor": "httpbin"})
+
+    seen: list[dict] = []
+
+    def handler(payload: dict) -> None:
+        seen.append(payload)
+
+    atherdlp.set_handler(handler)
+    atherdlp.install()
+
+    with respx.mock:
+        respx.get("https://httpbin.org/get").respond(200, json={"ok": True})
+        r = httpx.get("https://httpbin.org/get")
+        assert r.status_code == 200
+
+    atherdlp.uninstall()
+
+    assert len(seen) == 1
+    payload = seen[0]
+    assert payload["request"]["method"] == "GET"
+    assert payload["request"]["url"] == "https://httpbin.org/get"
+    assert payload["classification"]["kind"] == "test"
+    assert payload["classification"]["vendor"] == "httpbin"
+    assert payload["trace"]["trace_id"]
+    assert payload["trace"]["span_id"]
+    assert payload["trace"]["parent_span_id"] is None
+

atherdlp-0.0.2/tests/test_httpbin_file_upload.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import httpx
+import respx
+
+import atherdlp
+from atherdlp.classifier.providers import register_provider
+
+
+def test_httpbin_file_upload_is_extracted(tmp_path) -> None:
+    register_provider("httpbin.org", {"kind": "test", "vendor": "httpbin"})
+
+    p = tmp_path / "test.txt"
+    p.write_text("API_KEY=sk-1234567890\nhello world", encoding="utf-8")
+
+    seen: list[dict] = []
+
+    def handler(payload: dict) -> None:
+        seen.append(payload)
+
+    atherdlp.set_handler(handler)
+    atherdlp.install()
+
+    with respx.mock:
+        respx.post("https://httpbin.org/post").respond(200, json={"ok": True})
+        with p.open("rb") as f:
+            r = httpx.post("https://httpbin.org/post", files={"file": ("test.txt", f, "text/plain")})
+            assert r.status_code == 200
+
+    atherdlp.uninstall()
+
+    assert len(seen) == 1
+    body = seen[0]["request"]["body"]
+    assert set(body.keys()) == {"files", "fields"}
+    assert len(body["fields"]) == 0
+    assert len(body["files"]) == 1
+
+    file0 = body["files"][0]
+    assert file0["filename"] == "test.txt"
+    assert file0["content_type"] == "text/plain"
+    assert "API_KEY=sk-1234567890" in file0["content"]
+    assert "hello world" in file0["content"]
+    assert file0["size"] > 0
+

atherdlp-0.0.2/tests/test_httpbin_json_body.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import httpx
+import respx
+
+import atherdlp
+from atherdlp.classifier.providers import register_provider
+
+
+def test_httpbin_json_body_is_captured() -> None:
+    register_provider("httpbin.org", {"kind": "test", "vendor": "httpbin"})
+
+    seen_bodies: list[object] = []
+
+    def handler(payload: dict) -> None:
+        seen_bodies.append(payload["request"]["body"])
+
+    atherdlp.set_handler(handler)
+    atherdlp.install()
+
+    with respx.mock:
+        respx.post("https://httpbin.org/post").respond(200, json={"ok": True})
+        r = httpx.post("https://httpbin.org/post", json={"name": "subham", "secret": "123"})
+        assert r.status_code == 200
+
+    atherdlp.uninstall()
+
+    assert seen_bodies == [{"name": "subham", "secret": "123"}]
+

atherdlp-0.0.2/tests/test_httpbin_large_file_upload.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import httpx
+import respx
+
+import atherdlp
+from atherdlp.classifier.providers import register_provider
+
+
+def test_httpbin_large_file_upload_is_sampled(tmp_path) -> None:
+    register_provider("httpbin.org", {"kind": "test", "vendor": "httpbin"})
+
+    p = tmp_path / "big.txt"
+    p.write_text("A" * (3 * 1024 * 1024), encoding="utf-8")  # 3MB
+
+    seen: list[dict] = []
+
+    def handler(payload: dict) -> None:
+        seen.append(payload)
+
+    atherdlp.set_handler(handler)
+    atherdlp.install()
+
+    with respx.mock:
+        respx.post("https://httpbin.org/post").respond(200, json={"ok": True})
+        with p.open("rb") as f:
+            r = httpx.post("https://httpbin.org/post", files={"file": ("big.txt", f, "text/plain")})
+            assert r.status_code == 200
+
+    atherdlp.uninstall()
+
+    assert len(seen) == 1
+    body = seen[0]["request"]["body"]
+    assert len(body["files"]) == 1
+    file0 = body["files"][0]
+
+    assert file0["filename"] == "big.txt"
+    assert file0["content_type"] == "text/plain"
+    assert isinstance(file0["content"], dict)
+    assert file0["content"]["_sampled"] is True
+    assert file0["content"]["size"] == 3 * 1024 * 1024
+    assert isinstance(file0["content"]["samples"], list)
+    assert len(file0["content"]["samples"]) == 3
+    assert all(isinstance(s, str) for s in file0["content"]["samples"])
+