maskflow-evidence 0.1.0__tar.gz

maskflow_evidence-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+node_modules/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.pytest_cache/
+.idea/
+.coverage
+.mypy_cache/
+.ruff_cache/
+bench/indiapii/quality/.cache/

maskflow_evidence-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: maskflow-evidence
+Version: 0.1.0
+Summary: MaskFlow evidence layer: a metadata-only, verifiable record of what was masked -- never the values. Self-hosted emitters (stdout, file, syslog, webhook, OTLP), off by default.
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: maskflow-core<0.8,>=0.7.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: otlp
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25; extra == 'otlp'
+Requires-Dist: opentelemetry-sdk>=1.25; extra == 'otlp'
+Provides-Extra: webhook
+Requires-Dist: httpx>=0.27; extra == 'webhook'
+Description-Content-Type: text/markdown
+
+# maskflow-evidence
+
+A **metadata-only, verifiable record of what MaskFlow masked** — never the
+values themselves. Publishing the schema and shipping the emitters in the
+open lets any user confirm, by reading the code, exactly what leaves their
+environment.
+
+> Part of [MaskFlow](https://github.com/maskflow/maskflow). MIT, free
+> forever, no telemetry.
+
+## What an event looks like
+
+```json
+{"event_id":"…","ts":"2026-09-07T12:00:00Z","session_id":"…","service":"support-bot",
+ "environment":"prod","entity_type":"AADHAAR","count":1,"score":0.98,
+ "recognizer":"pattern:AADHAAR","action":"masked","provider":"openai","model":"gpt-4o",
+ "pack_version":"0.5.0","engine_version":"0.6.0"}
+```
+
+There is **no field that can carry free text.** Every string is a bounded
+slug; there is no place for a detected value, a placeholder, or the mapping
+between them. This is enforced structurally in `schema.py` and in CI by
+`tests/test_schema_metadata_only.py`.
+
+## Off by default
+
+Nothing is emitted unless you turn it on. In `.maskflowrc`:
+
+```toml
+[evidence]
+enabled     = true
+sink        = "file"          # stdout | file | syslog | webhook | otlp
+path        = "evidence.log"
+service     = "support-bot"
+environment = "prod"
+```
+
+The gateway reads `MASKFLOW_GATEWAY_EVIDENCE_*` environment variables with
+the same names.
+
+## Sinks
+
+| sink | transport | extra |
+|---|---|---|
+| `stdout` | one JSON line per event | — |
+| `file` | size-rotated JSON lines | — |
+| `syslog` | `SysLogHandler` | — |
+| `webhook` | `POST` JSON per event | `maskflow-evidence[webhook]` |
+| `otlp` | OpenTelemetry log records | `maskflow-evidence[otlp]` |
+
+## What is deliberately **not** collected
+
+Raw values, masked values, the mapping, request/response bodies, prompt
+text, and any user identifier beyond a caller-supplied opaque `session_id`.
+See `docs/evidence.md` for the full statement.

maskflow_evidence-0.1.0/README.md

@@ -0,0 +1,55 @@
+# maskflow-evidence
+
+A **metadata-only, verifiable record of what MaskFlow masked** — never the
+values themselves. Publishing the schema and shipping the emitters in the
+open lets any user confirm, by reading the code, exactly what leaves their
+environment.
+
+> Part of [MaskFlow](https://github.com/maskflow/maskflow). MIT, free
+> forever, no telemetry.
+
+## What an event looks like
+
+```json
+{"event_id":"…","ts":"2026-09-07T12:00:00Z","session_id":"…","service":"support-bot",
+ "environment":"prod","entity_type":"AADHAAR","count":1,"score":0.98,
+ "recognizer":"pattern:AADHAAR","action":"masked","provider":"openai","model":"gpt-4o",
+ "pack_version":"0.5.0","engine_version":"0.6.0"}
+```
+
+There is **no field that can carry free text.** Every string is a bounded
+slug; there is no place for a detected value, a placeholder, or the mapping
+between them. This is enforced structurally in `schema.py` and in CI by
+`tests/test_schema_metadata_only.py`.
+
+## Off by default
+
+Nothing is emitted unless you turn it on. In `.maskflowrc`:
+
+```toml
+[evidence]
+enabled     = true
+sink        = "file"          # stdout | file | syslog | webhook | otlp
+path        = "evidence.log"
+service     = "support-bot"
+environment = "prod"
+```
+
+The gateway reads `MASKFLOW_GATEWAY_EVIDENCE_*` environment variables with
+the same names.
+
+## Sinks
+
+| sink | transport | extra |
+|---|---|---|
+| `stdout` | one JSON line per event | — |
+| `file` | size-rotated JSON lines | — |
+| `syslog` | `SysLogHandler` | — |
+| `webhook` | `POST` JSON per event | `maskflow-evidence[webhook]` |
+| `otlp` | OpenTelemetry log records | `maskflow-evidence[otlp]` |
+
+## What is deliberately **not** collected
+
+Raw values, masked values, the mapping, request/response bodies, prompt
+text, and any user identifier beyond a caller-supplied opaque `session_id`.
+See `docs/evidence.md` for the full statement.

maskflow_evidence-0.1.0/contrib/grafana-dashboard.json

@@ -0,0 +1,117 @@
+{
+  "__inputs": [
+    {
+      "name": "DS_PROMETHEUS",
+      "label": "Prometheus",
+      "description": "Prometheus datasource scraping the MaskFlow Gateway /metrics endpoint",
+      "type": "datasource",
+      "pluginId": "prometheus",
+      "pluginName": "Prometheus"
+    }
+  ],
+  "annotations": { "list": [] },
+  "description": "MaskFlow evidence: what was masked, from gateway Prometheus metrics. Panels only -- no compliance-control framing (pending issue #42).",
+  "editable": true,
+  "graphTooltip": 0,
+  "panels": [
+    {
+      "type": "row",
+      "title": "Evidence emission",
+      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 0 },
+      "id": 10
+    },
+    {
+      "type": "stat",
+      "title": "Evidence events emitted (5m rate)",
+      "description": "maskflow_evidence_emitted_total -- zero unless [evidence] is enabled on the gateway.",
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "gridPos": { "h": 6, "w": 8, "x": 0, "y": 1 },
+      "id": 11,
+      "targets": [
+        { "expr": "sum(rate(maskflow_evidence_emitted_total[5m]))", "refId": "A" }
+      ],
+      "fieldConfig": { "defaults": { "unit": "ops" }, "overrides": [] }
+    },
+    {
+      "type": "timeseries",
+      "title": "Evidence events by sink",
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "gridPos": { "h": 6, "w": 16, "x": 8, "y": 1 },
+      "id": 12,
+      "targets": [
+        {
+          "expr": "sum by (sink) (rate(maskflow_evidence_emitted_total[5m]))",
+          "legendFormat": "{{sink}}",
+          "refId": "A"
+        }
+      ]
+    },
+    {
+      "type": "row",
+      "title": "What was masked",
+      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 7 },
+      "id": 20
+    },
+    {
+      "type": "timeseries",
+      "title": "Detections by entity type (request side, 5m rate)",
+      "description": "maskflow_detections_total{direction=\"request\"} -- PII masked before it reached the provider.",
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "gridPos": { "h": 9, "w": 12, "x": 0, "y": 8 },
+      "id": 21,
+      "targets": [
+        {
+          "expr": "sum by (entity_type) (rate(maskflow_detections_total{direction=\"request\"}[5m]))",
+          "legendFormat": "{{entity_type}}",
+          "refId": "A"
+        }
+      ]
+    },
+    {
+      "type": "piechart",
+      "title": "Detection mix by entity type (last 24h)",
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "gridPos": { "h": 9, "w": 12, "x": 12, "y": 8 },
+      "id": 22,
+      "targets": [
+        {
+          "expr": "sum by (entity_type) (increase(maskflow_detections_total[24h]))",
+          "legendFormat": "{{entity_type}}",
+          "refId": "A"
+        }
+      ]
+    },
+    {
+      "type": "timeseries",
+      "title": "Mask stage latency (p50 / p95 / p99)",
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "gridPos": { "h": 8, "w": 24, "x": 0, "y": 17 },
+      "id": 30,
+      "targets": [
+        {
+          "expr": "histogram_quantile(0.50, sum by (le) (rate(maskflow_stage_latency_seconds_bucket{stage=\"mask\"}[5m])))",
+          "legendFormat": "p50",
+          "refId": "A"
+        },
+        {
+          "expr": "histogram_quantile(0.95, sum by (le) (rate(maskflow_stage_latency_seconds_bucket{stage=\"mask\"}[5m])))",
+          "legendFormat": "p95",
+          "refId": "B"
+        },
+        {
+          "expr": "histogram_quantile(0.99, sum by (le) (rate(maskflow_stage_latency_seconds_bucket{stage=\"mask\"}[5m])))",
+          "legendFormat": "p99",
+          "refId": "C"
+        }
+      ],
+      "fieldConfig": { "defaults": { "unit": "s" }, "overrides": [] }
+    }
+  ],
+  "schemaVersion": 39,
+  "tags": ["maskflow", "evidence", "pii"],
+  "templating": { "list": [] },
+  "time": { "from": "now-6h", "to": "now" },
+  "title": "MaskFlow Evidence",
+  "uid": "maskflow-evidence",
+  "version": 1
+}

maskflow_evidence-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "maskflow-evidence"
+version = "0.1.0"
+description = "MaskFlow evidence layer: a metadata-only, verifiable record of what was masked -- never the values. Self-hosted emitters (stdout, file, syslog, webhook, OTLP), off by default."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    # Span / Mapping / Strategy / PIIType come from the engine, and the
+    # metadata-only leak assertion reuses core's detect_patterns_only(). No
+    # SDK dependency -- the evidence layer never masks, it only records what
+    # a mask() call already decided.
+    "maskflow-core>=0.7.0,<0.8",
+]
+
+[project.optional-dependencies]
+# The webhook emitter POSTs one JSON object per event. httpx only; kept out
+# of the base install so `import maskflow_evidence` stays dependency-light
+# for the stdout/file/syslog sinks (all stdlib).
+webhook = [
+    "httpx>=0.27",
+]
+# The OTLP emitter ships events as OpenTelemetry log records. The OTel SDK
+# tree is large; opt in only if you already run an OTel collector.
+otlp = [
+    "opentelemetry-sdk>=1.25",
+    "opentelemetry-exporter-otlp-proto-http>=1.25",
+]
+dev = [
+    "pytest>=8.0",
+    "hypothesis>=6.100",
+    "httpx>=0.27",
+]
+
+[tool.uv.sources]
+maskflow-core = { workspace = true }
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/maskflow_evidence"]
+
+[tool.pytest.ini_options]
+markers = [
+    "leak: guards against a raw or masked value, or the mapping, reaching an evidence event",
+]

maskflow_evidence-0.1.0/src/maskflow_evidence/__init__.py

@@ -0,0 +1,50 @@
+"""MaskFlow evidence layer.
+
+A metadata-only, verifiable record of *what was masked* -- never the values.
+See ``docs/evidence.md`` for the schema, what is deliberately not collected,
+and the self-hosted setup guide.
+
+Off by default: nothing is emitted unless ``[evidence] enabled = true`` (or
+the equivalent env var) selects a sink.
+"""
+
+from __future__ import annotations
+
+from .config import EvidenceConfig
+from .derive import (
+    EventContext,
+    action_for_strategy,
+    events_from_mapping,
+    events_from_spans,
+)
+from .emitters import Emitter, NullEmitter, SafeEmitter, build_emitter
+from .guard import (
+    MetadataOnlyViolation,
+    assert_no_pii,
+    assert_schema_is_metadata_only,
+    scan_for_pii,
+)
+from .schema import ACTIONS, EvidenceEvent, EvidenceSchemaError
+from .versions import engine_version, pack_version, pack_versions
+
+__all__ = [
+    "ACTIONS",
+    "EvidenceConfig",
+    "EvidenceEvent",
+    "EvidenceSchemaError",
+    "EventContext",
+    "Emitter",
+    "NullEmitter",
+    "SafeEmitter",
+    "MetadataOnlyViolation",
+    "action_for_strategy",
+    "assert_no_pii",
+    "assert_schema_is_metadata_only",
+    "build_emitter",
+    "events_from_mapping",
+    "events_from_spans",
+    "engine_version",
+    "pack_version",
+    "pack_versions",
+    "scan_for_pii",
+]

maskflow_evidence-0.1.0/src/maskflow_evidence/config.py

@@ -0,0 +1,125 @@
+"""``EvidenceConfig`` -- the resolved settings :func:`build_emitter` needs,
+plus the two ways to obtain it:
+
+* :meth:`EvidenceConfig.from_rootconfig` -- from a ``maskflow_core`` resolved
+  config's ``[evidence]`` section (the CLI path);
+* :meth:`EvidenceConfig.from_env` -- from ``MASKFLOW_..._EVIDENCE_*``
+  environment variables (the gateway path, which is env-only by design).
+
+Evidence is **off by default** in both.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+_SINKS = ("stdout", "file", "syslog", "webhook", "otlp")
+
+
+def _as_bool(value: Any, default: bool) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in ("1", "true", "yes", "on")
+    return default
+
+
+def _as_int(value: Any, default: int) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _as_float(value: Any, default: float) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+@dataclass(frozen=True)
+class EvidenceConfig:
+    enabled: bool = False
+    sink: str = "file"
+    # file sink
+    path: str = "evidence.log"
+    max_bytes: int = 10_000_000
+    backups: int = 5
+    # webhook / otlp sink
+    url: str = ""
+    timeout: float = 2.0
+    # syslog sink -- empty host means the local socket (/dev/log, or the
+    # macOS equivalent), which is what most deployments want.
+    syslog_host: str = ""
+    syslog_port: int = 514
+    # context stamped onto every event
+    service: str = "maskflow"
+    environment: str = "production"
+
+    def __post_init__(self) -> None:
+        if self.sink not in _SINKS:
+            raise ValueError(f"[evidence] sink must be one of {_SINKS}, got {self.sink!r}")
+
+    def syslog_address(self) -> str | tuple[str, int]:
+        if self.syslog_host:
+            return (self.syslog_host, self.syslog_port)
+        return "/dev/log"
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> EvidenceConfig:
+        base = cls()
+        return cls(
+            enabled=_as_bool(data.get("enabled"), base.enabled),
+            sink=str(data.get("sink", base.sink)),
+            path=str(data.get("path", base.path)),
+            max_bytes=_as_int(data.get("max_bytes"), base.max_bytes),
+            backups=_as_int(data.get("backups"), base.backups),
+            url=str(data.get("url", base.url)),
+            timeout=_as_float(data.get("timeout"), base.timeout),
+            syslog_host=str(data.get("syslog_host", base.syslog_host)),
+            syslog_port=_as_int(data.get("syslog_port"), base.syslog_port),
+            service=str(data.get("service", base.service)),
+            environment=str(data.get("environment", base.environment)),
+        )
+
+    @classmethod
+    def from_rootconfig(cls, root_config: Any) -> EvidenceConfig:
+        """Read the ``evidence`` section off a ``maskflow_core`` ``RootConfig``
+        (or anything with a compatible ``.evidence`` attribute). A config with
+        no ``[evidence]`` section yields the disabled default."""
+        section = getattr(root_config, "evidence", None)
+        if section is None:
+            return cls()
+        if isinstance(section, Mapping):
+            return cls.from_dict(section)
+        # a dataclass section -> pull known attributes
+        keys = (
+            "enabled",
+            "sink",
+            "path",
+            "max_bytes",
+            "backups",
+            "url",
+            "timeout",
+            "syslog_host",
+            "syslog_port",
+            "service",
+            "environment",
+        )
+        return cls.from_dict({k: getattr(section, k) for k in keys if hasattr(section, k)})
+
+    @classmethod
+    def from_env(cls, prefix: str, env: Mapping[str, str] | None = None) -> EvidenceConfig:
+        """Build from ``{prefix}ENABLED``, ``{prefix}SINK``, ... (e.g.
+        ``prefix="MASKFLOW_GATEWAY_EVIDENCE_"``)."""
+        source = env if env is not None else os.environ
+        picked = {
+            key[len(prefix) :].lower(): value
+            for key, value in source.items()
+            if key.startswith(prefix)
+        }
+        return cls.from_dict(picked)

maskflow_evidence-0.1.0/src/maskflow_evidence/derive.py

@@ -0,0 +1,136 @@
+"""Turn a masking decision into evidence events -- without ever reading a
+detected value.
+
+``derive.py`` may touch ``Span.start``/``end``/``entity_type``/``score``/
+``recognizer`` and ``MappingEntry.entity_type``/``strategy``/``score``/
+``recognizer``. It must never read ``Span.text`` or ``MappingEntry.original``
+-- ``tests/test_derive_no_value_access.py`` enforces this with an AST check.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+
+from maskflow_core import Mapping, Span
+from maskflow_core.strategies import Strategy
+
+from .schema import EvidenceEvent
+from .versions import engine_version, pack_version
+
+# maskflow_core.Strategy -> evidence `action`. HASH collapses to "masked":
+# from an evidence standpoint the value was replaced by something
+# non-recoverable, same category as MASK/REDACT is "redacted".
+_STRATEGY_ACTION: dict[Strategy, str] = {
+    Strategy.REPLACE: "masked",
+    Strategy.MASK: "masked",
+    Strategy.HASH: "masked",
+    Strategy.REDACT: "redacted",
+    Strategy.SURROGATE: "surrogate",
+}
+
+
+@dataclass(frozen=True)
+class EventContext:
+    """The invariant part of every event from one masking call. All fields
+    are validated as slugs by ``EvidenceEvent`` -- a caller that passes an
+    email as ``session_id`` gets an ``EvidenceSchemaError``."""
+
+    session_id: str
+    service: str
+    environment: str
+    provider: str | None = None
+    model: str | None = None
+
+
+def _emit_group(
+    ctx: EventContext,
+    entity_type: str,
+    recognizer: str,
+    action: str,
+    scores: list[float],
+) -> EvidenceEvent:
+    return EvidenceEvent(
+        entity_type=entity_type,
+        count=len(scores),
+        # The most conservative claim: the weakest detection in the group.
+        score=min(scores),
+        recognizer=recognizer,
+        action=action,
+        service=ctx.service,
+        environment=ctx.environment,
+        session_id=ctx.session_id,
+        provider=ctx.provider,
+        model=ctx.model,
+        pack_version=pack_version(),
+        engine_version=engine_version(),
+    )
+
+
+def events_from_spans(
+    spans: Sequence[Span],
+    ctx: EventContext,
+    *,
+    strategy_for: Callable[[str], str] | None = None,
+    dropped: Iterable[Span] = (),
+) -> list[EvidenceEvent]:
+    """One event per ``(entity_type, recognizer, action)`` across the
+    resolved ``spans`` (plus any ``dropped`` spans, which become
+    ``action="passed"``).
+
+    ``strategy_for`` maps an entity-type name to an evidence action
+    (``"masked"``/``"redacted"``/``"surrogate"``); when omitted every
+    resolved span is treated as ``"masked"``.
+    """
+    groups: dict[tuple[str, str, str], list[float]] = defaultdict(list)
+
+    for span in spans:
+        etype = span.entity_type.value
+        action = strategy_for(etype) if strategy_for is not None else "masked"
+        groups[(etype, span.recognizer, action)].append(span.score)
+
+    for span in dropped:
+        groups[(span.entity_type.value, span.recognizer, "passed")].append(span.score)
+
+    return [
+        _emit_group(ctx, etype, recognizer, action, scores)
+        for (etype, recognizer, action), scores in sorted(groups.items())
+    ]
+
+
+def action_for_strategy(strategy: Strategy) -> str:
+    return _STRATEGY_ACTION.get(strategy, "masked")
+
+
+def events_from_mapping(
+    mapping: Mapping,
+    ctx: EventContext,
+    *,
+    only_tokens: Iterable[str] | None = None,
+) -> list[EvidenceEvent]:
+    """Events from a ``mask_with_policy`` result -- the gateway path, which
+    holds the session ``Mapping`` rather than the span list.
+
+    ``only_tokens`` restricts to tokens added by the current request (the
+    gateway diffs the mapping before/after each mask call). ``score`` and
+    ``recognizer`` come from the ``MappingEntry`` when present (core >=
+    0.6.x populates them); otherwise ``recognizer`` is ``"unknown"`` and the
+    group score defaults to ``1.0``.
+    """
+    wanted = set(only_tokens) if only_tokens is not None else None
+    groups: dict[tuple[str, str, str], list[float]] = defaultdict(list)
+
+    for token, entry in mapping.items():
+        if wanted is not None and token not in wanted:
+            continue
+        etype = entry.entity_type.value
+        action = action_for_strategy(entry.strategy)
+        recognizer = getattr(entry, "recognizer", None) or "unknown"
+        score = getattr(entry, "score", None)
+        groups[(etype, recognizer, action)].append(1.0 if score is None else float(score))
+
+    return [
+        _emit_group(ctx, etype, recognizer, action, scores)
+        for (etype, recognizer, action), scores in sorted(groups.items())
+    ]