ciphergate-cli 0.7.0__py3-none-any.whl

ciphergate/pipeline/streams.py

@@ -0,0 +1,152 @@
+"""Binary-stream variants of the single-file operations (Python API counterpart of CLI ``-``).
+
+The pipeline reads its input twice and checks it did not change, so a stream is first spooled
+into a private workspace (``StdioWorkspace``: owner-only on POSIX), capped at
+``max_input_bytes`` while reading. ``sanitize_stream`` sanitizes into the same workspace and
+copies to ``output`` only after every check passed; a blocked, review or failed run writes
+nothing to it. The workspace is removed on success, failure and interruption.
+
+Streams must be binary (``open(..., "rb")``, ``io.BytesIO``); the format is always required
+because there is no file name to infer it from. Reports show ``<stream>`` as the path.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import IO
+
+from ciphergate.config import RuntimeSettings
+from ciphergate.constants import InputFormat
+from ciphergate.errors import OutputWriteError, UsageError
+from ciphergate.models.context import ContextInput
+from ciphergate.models.report import RunReport
+from ciphergate.pipeline.sanitizer import (
+    SanitizeOptions,
+    inspect_file,
+    plan_file,
+    rescan_file,
+    sanitize_file,
+)
+from ciphergate.pipeline.stdio import StdioWorkspace
+from ciphergate.policy.validator import Policy
+from ciphergate.transforms.keys import KeyProvider
+
+STREAM_DISPLAY = "<stream>"
+_CHUNK = 1024 * 1024
+
+
+def _require_format(fmt: InputFormat | None) -> InputFormat:
+    if fmt is None:
+        raise UsageError("a stream needs an explicit format", code="format_required")
+    return InputFormat(fmt)
+
+
+def _spool(
+    ws: StdioWorkspace, stream: IO[bytes], fmt: InputFormat, runtime: RuntimeSettings
+) -> Path:
+    return ws.spool_input(stream, fmt, runtime.max_input_bytes, label="input stream")
+
+
+def inspect_stream(
+    stream: IO[bytes],
+    policy: Policy,
+    context: ContextInput | None = None,
+    *,
+    fmt: InputFormat,
+    runtime: RuntimeSettings | None = None,
+    keys: KeyProvider | None = None,
+) -> RunReport:
+    """Detect and evaluate data read from a binary stream; writes no data anywhere."""
+    fmt, runtime = _require_format(fmt), runtime or RuntimeSettings()
+    with StdioWorkspace() as ws:
+        report = inspect_file(_spool(ws, stream, fmt, runtime), policy, context,
+                              runtime=runtime, fmt=fmt, keys=keys)  # fmt: skip
+    report.input["path"] = STREAM_DISPLAY
+    return report
+
+
+def plan_stream(
+    stream: IO[bytes],
+    policy: Policy,
+    context: ContextInput | None = None,
+    *,
+    fmt: InputFormat,
+    runtime: RuntimeSettings | None = None,
+    keys: KeyProvider | None = None,
+) -> RunReport:
+    """Preview the decisions ``sanitize_stream`` would make; writes no data anywhere."""
+    fmt, runtime = _require_format(fmt), runtime or RuntimeSettings()
+    with StdioWorkspace() as ws:
+        report = plan_file(_spool(ws, stream, fmt, runtime), policy, context,
+                           runtime=runtime, fmt=fmt, keys=keys)  # fmt: skip
+    report.input["path"] = STREAM_DISPLAY
+    return report
+
+
+def rescan_stream(
+    stream: IO[bytes],
+    policy: Policy,
+    context: ContextInput | None = None,
+    *,
+    fmt: InputFormat,
+    strict: bool | None = None,
+    runtime: RuntimeSettings | None = None,
+) -> RunReport:
+    """Report residual findings in (sanitized) data read from a binary stream. Read-only."""
+    fmt, runtime = _require_format(fmt), runtime or RuntimeSettings()
+    with StdioWorkspace() as ws:
+        report = rescan_file(_spool(ws, stream, fmt, runtime), policy, context,
+                             strict=strict, runtime=runtime, fmt=fmt)  # fmt: skip
+    report.input["path"] = STREAM_DISPLAY
+    return report
+
+
+def sanitize_stream(
+    stream: IO[bytes],
+    output: IO[bytes],
+    policy: Policy,
+    context: ContextInput | None = None,
+    options: SanitizeOptions | None = None,
+) -> RunReport:
+    """Sanitize a binary stream into ``output``; ``output`` is written only if the run succeeded.
+
+    ``options.format`` is required. Without ``options.apply`` this is a plan and nothing is
+    written. If copying to ``output`` fails part-way, ``OutputWriteError`` says so explicitly:
+    ``output`` may then hold an incomplete (but sanitized) prefix.
+    """
+    options = options or SanitizeOptions()
+    fmt = _require_format(options.format)
+    runtime = options.runtime or RuntimeSettings()
+    run_options = SanitizeOptions(
+        apply=options.apply, force=False, keys=options.keys, format=fmt, runtime=runtime
+    )
+    with StdioWorkspace() as ws:
+        staged = ws.output_path()
+        report = sanitize_file(_spool(ws, stream, fmt, runtime), staged, policy, context,
+                               run_options)  # fmt: skip
+        report.input["path"] = STREAM_DISPLAY
+        report.output["path"] = STREAM_DISPLAY
+        if report.output.get("written"):
+            _copy(staged, output)
+    return report
+
+
+def _copy(path: Path, output: IO[bytes]) -> None:
+    try:
+        with path.open("rb") as fh:
+            shutil.copyfileobj(fh, output, _CHUNK)
+        output.flush()
+    except KeyboardInterrupt:
+        raise OutputWriteError(
+            "interrupted while writing the output stream; it may be incomplete",
+            code="stream_interrupted",
+        ) from None
+    except TypeError:
+        raise UsageError(
+            "output must be a binary stream (open it with 'wb')", code="stream_not_binary"
+        ) from None
+    except OSError:
+        raise OutputWriteError(
+            "failed to write the output stream; it may be incomplete", code="stream_write_failed"
+        ) from None

ciphergate/policy/__init__.py

@@ -0,0 +1,26 @@
+"""Policy loading, validation, context resolution and the decision engine."""
+
+from ciphergate.policy.context import GateIssue, evaluate_gates, resolve_context
+from ciphergate.policy.engine import Decision, PolicyEngine
+from ciphergate.policy.validator import (
+    Policy,
+    ValidationResult,
+    compile_policy,
+    load_policy,
+    load_policy_text,
+    validate_policy,
+)
+
+__all__ = [
+    "Decision",
+    "GateIssue",
+    "Policy",
+    "PolicyEngine",
+    "ValidationResult",
+    "compile_policy",
+    "evaluate_gates",
+    "load_policy",
+    "load_policy_text",
+    "resolve_context",
+    "validate_policy",
+]

ciphergate/policy/context.py

@@ -0,0 +1,203 @@
+"""Context resolution (policy pins vs. caller input) and run-level environment guardrails.
+
+Environment values are *declared* context. CipherGate cannot verify that data really came from the
+stated environment; CI pipelines should source these values from controlled configuration.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from ciphergate.constants import (
+    CREDENTIAL_DETECTORS,
+    NON_PRODUCTION_DESTINATIONS,
+    Destination,
+    Environment,
+    InputFormat,
+    ReasonCode,
+    TargetEnvironment,
+)
+from ciphergate.errors import ContextError
+from ciphergate.models.context import (
+    CONTEXT_FIELDS,
+    ContextInput,
+    ContextSource,
+    EffectiveContext,
+)
+from ciphergate.policy.validator import Policy
+
+
+@dataclass(frozen=True, slots=True)
+class GateIssue:
+    reason_code: ReasonCode
+    severity: Literal["block", "review"]
+    message: str
+    field: str | None = None
+
+    def to_dict(self) -> dict[str, str | None]:
+        return {
+            "reason_code": str(self.reason_code),
+            "severity": self.severity,
+            "field": self.field,
+            "message": self.message,
+        }
+
+
+def resolve_context(policy: Policy, given: ContextInput | None = None) -> EffectiveContext:
+    """Combine policy-pinned context with caller input; conflicts fail unless overridable."""
+    given = given or ContextInput()
+    pins = policy.document.context
+    values: dict[str, object] = {}
+    sources: dict[str, ContextSource] = {}
+    for name in CONTEXT_FIELDS:
+        pinned = getattr(pins, name)
+        supplied = getattr(given, name)
+        if pinned is not None and supplied is not None and pinned != supplied:
+            if name not in pins.allow_cli_override:
+                raise ContextError(
+                    f"'{name}' supplied by the caller conflicts with the value pinned by the "
+                    "policy; "
+                    "use a policy for that context or add it to context.allow_cli_override",
+                    code=str(ReasonCode.ENVIRONMENT_CONTEXT_CONFLICT),
+                )
+            values[name], sources[name] = supplied, "cli_override"
+        elif pinned is not None:
+            values[name], sources[name] = pinned, "policy"
+        elif supplied is not None:
+            values[name], sources[name] = supplied, "cli"
+        else:
+            values[name], sources[name] = None, "unset"
+    return EffectiveContext(sources=sources, **values)  # type: ignore[arg-type]
+
+
+def _approval_matches(policy: Policy, ctx: EffectiveContext) -> str | None:
+    """An approval must name every context dimension the run supplies (no implicit widening)."""
+    for transfer in policy.document.transfers:
+        if ctx.environment not in transfer.from_environments:
+            continue
+        if ctx.target_environment is not None and (
+            ctx.target_environment not in transfer.to_target_environments
+        ):
+            continue
+        if ctx.destination is not None and ctx.destination not in transfer.to_destinations:
+            continue
+        return transfer.id
+    return None
+
+
+def evaluate_gates(
+    policy: Policy, ctx: EffectiveContext, fmt: InputFormat | None = None
+) -> tuple[list[GateIssue], list[str]]:
+    """Run-level checks that no rule can override. Returns (issues, approvals_used).
+
+    A missing destination counts as untrusted: it never relaxes the strict/rescan requirements.
+    """
+    doc = policy.document
+    issues: list[GateIssue] = []
+    approvals: list[str] = []
+    req = doc.requirements
+
+    if req.environment and ctx.environment is None:
+        issues.append(
+            GateIssue(
+                ReasonCode.ENVIRONMENT_REQUIRED_BUT_MISSING,
+                "block",
+                "source environment is required (--environment)",
+                "environment",
+            )
+        )
+    if req.target_environment and ctx.target_environment is None:
+        issues.append(
+            GateIssue(
+                ReasonCode.TARGET_ENVIRONMENT_REQUIRED_BUT_MISSING,
+                "block",
+                "target environment is required (--target-environment)",
+                "target_environment",
+            )
+        )
+    if req.destination and ctx.destination is None:
+        issues.append(
+            GateIssue(
+                ReasonCode.DESTINATION_REQUIRED_BUT_MISSING,
+                "block",
+                "destination is required (--destination)",
+                "destination",
+            )
+        )
+
+    if doc.settings.strict:
+        for name, unknown in (
+            ("environment", Environment.UNKNOWN),
+            ("target_environment", TargetEnvironment.UNKNOWN),
+            ("destination", Destination.UNKNOWN),
+        ):
+            if getattr(ctx, name) == unknown:
+                issues.append(
+                    GateIssue(
+                        ReasonCode.UNKNOWN_CONTEXT_REQUIRES_REVIEW,
+                        "review",
+                        f"{name} is 'unknown'; strict policies require known "
+                        "context before release",
+                        name,
+                    )
+                )
+
+    prd_to_nonprod = ctx.environment == Environment.PRD and (
+        ctx.target_environment in (TargetEnvironment.DEV, TargetEnvironment.STG)
+        or ctx.destination in NON_PRODUCTION_DESTINATIONS
+    )
+    if prd_to_nonprod:
+        approval = _approval_matches(policy, ctx)
+        if approval is None:
+            issues.append(
+                GateIssue(
+                    ReasonCode.PRD_TO_NONPRODUCTION_BLOCKED,
+                    "block",
+                    "production-origin data headed to a non-production target is blocked "
+                    "unless the "
+                    "policy contains a reviewed 'transfers' approval for this context",
+                )
+            )
+        else:
+            approvals.append(approval)
+
+    untrusted = ctx.is_untrusted or ctx.target_environment == TargetEnvironment.PRD
+    if untrusted and not doc.settings.strict:
+        issues.append(
+            GateIssue(
+                ReasonCode.STRICT_POLICY_REQUIRED,
+                "block",
+                "external, unknown, missing or production targets require a strict policy",
+            )
+        )
+    if untrusted and not doc.settings.rescan.enabled:
+        issues.append(
+            GateIssue(
+                ReasonCode.RESCAN_REQUIRED,
+                "block",
+                "external, unknown, missing or production targets require the rescan gate",
+            )
+        )
+    if untrusted and CREDENTIAL_DETECTORS & set(doc.detectors.disabled):
+        issues.append(
+            GateIssue(
+                ReasonCode.CREDENTIAL_DETECTION_REQUIRED,
+                "block",
+                "secret_pattern/field_name detectors must stay enabled for this target",
+            )
+        )
+    if (
+        ctx.is_untrusted
+        and fmt in (InputFormat.JSON, InputFormat.JSONL)
+        and not doc.settings.scan_json_keys
+    ):
+        issues.append(
+            GateIssue(
+                ReasonCode.KEY_SCAN_REQUIRED,
+                "block",
+                "JSON keys are not scanned (settings.scan_json_keys: false); keys can carry "
+                "data and must be scanned for an untrusted or missing destination",
+            )
+        )
+    return issues, approvals

ciphergate/policy/engine.py

@@ -0,0 +1,194 @@
+"""The policy engine: (finding, context, format) -> Decision. Deterministic and side-effect free.
+
+See ``ciphergate.policy.precedence`` for the precedence levels. After a rule/default/fallback is
+selected, engine hard constraints are applied; they cannot be overridden by any rule:
+
+* credentials are never allowed (nor generalized/date-shifted) — forced to ``block``;
+* an ``allow`` of a high-risk category toward an untrusted or missing destination (or an
+  external/unknown target environment) without
+  ``acknowledge_risk`` becomes ``review``;
+* transforms that cannot apply to the location (e.g. ``drop_field`` on a text line, value
+  transforms on JSON keys/CSV header cells) become ``review`` with ``unsupported_transform``, or
+  ``block`` when the finding is a credential.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ciphergate.constants import (
+    CREDENTIAL_CATEGORY,
+    CREDENTIAL_PERMITTED_ACTIONS,
+    LINE_FORMATS,
+    VALUE_TRANSFORM_ACTIONS,
+    Action,
+    InputFormat,
+    ReasonCode,
+)
+from ciphergate.models.context import EffectiveContext
+from ciphergate.models.finding import Finding
+from ciphergate.models.policy import ActionParams, EmptyParams
+from ciphergate.policy.precedence import (
+    LEVEL_DEFAULT,
+    LEVEL_FALLBACK,
+    LEVEL_GUARDRAIL,
+    LEVEL_HARD_CONSTRAINT,
+    LEVEL_HARD_RULE,
+    LEVEL_NAMES,
+)
+from ciphergate.policy.validator import (
+    MATCH_CONFIDENCE_ONLY,
+    MATCH_YES,
+    CompiledRule,
+    Policy,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Decision:
+    action: Action
+    reason_code: ReasonCode
+    level: int
+    rule_id: str | None = None
+    rule_reason: str | None = None
+    params: ActionParams = field(default_factory=EmptyParams)
+    matched_on: tuple[str, ...] = ()
+    overridden_rule_id: str | None = None
+
+    @property
+    def requires_review(self) -> bool:
+        return self.action == Action.REVIEW
+
+    @property
+    def level_name(self) -> str:
+        return LEVEL_NAMES[self.level]
+
+    def to_dict(self) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "action": str(self.action),
+            "reason_code": str(self.reason_code),
+            "precedence": self.level_name,
+            "rule_id": self.rule_id,
+        }
+        if self.rule_reason:
+            data["rule_reason"] = self.rule_reason
+        if self.matched_on:
+            data["matched_on"] = list(self.matched_on)
+        if self.overridden_rule_id:
+            data["overridden_rule_id"] = self.overridden_rule_id
+        data["requires_review"] = self.requires_review
+        return data
+
+
+class PolicyEngine:
+    def __init__(self, policy: Policy) -> None:
+        self.policy = policy
+
+    def decide(self, finding: Finding, ctx: EffectiveContext, fmt: InputFormat) -> Decision:
+        decision = self._select(finding, ctx, fmt)
+        return self._apply_hard_constraints(decision, finding, ctx, fmt)
+
+    def _select(self, finding: Finding, ctx: EffectiveContext, fmt: InputFormat) -> Decision:
+        matched: list[CompiledRule] = []
+        confidence_miss = False
+        for rule in self.policy.rules:
+            result = rule.evaluate(finding, ctx, fmt)
+            if result == MATCH_YES:
+                matched.append(rule)
+            elif result == MATCH_CONFIDENCE_ONLY:
+                confidence_miss = True
+        if matched:
+            level = min(r.level for r in matched)
+            at_level = [r for r in matched if r.level == level]
+            priority = max(r.rule.priority for r in at_level)
+            top = [r for r in at_level if r.rule.priority == priority]
+            if len({(r.rule.action, r.params.model_dump_json()) for r in top}) > 1:
+                # Unreachable for validated policies; fail closed rather than pick by order.
+                return Decision(
+                    Action.BLOCK,
+                    ReasonCode.POLICY_CONFLICT,
+                    LEVEL_HARD_CONSTRAINT,
+                    rule_id=",".join(sorted(r.id for r in top)),
+                )
+            chosen = top[0]
+            if level == LEVEL_HARD_RULE and chosen.rule.action == Action.BLOCK:
+                reason = (
+                    ReasonCode.CREDENTIAL_DETECTED_HARD_BLOCK
+                    if finding.category == CREDENTIAL_CATEGORY
+                    else ReasonCode.EXPLICIT_HARD_BLOCK
+                )
+            elif level == LEVEL_GUARDRAIL:
+                reason = ReasonCode.ENVIRONMENT_GUARDRAIL
+            else:
+                reason = ReasonCode.EXPLICIT_POLICY_MATCH
+            return Decision(
+                action=chosen.rule.action,
+                reason_code=reason,
+                level=level,
+                rule_id=chosen.id,
+                rule_reason=chosen.rule.reason,
+                params=chosen.params,
+                matched_on=chosen.selectors(),
+            )
+        default = self.policy.default_for(finding.category)
+        if default is not None:
+            return Decision(
+                action=default.action,
+                reason_code=ReasonCode.PROFILE_DEFAULT,
+                level=LEVEL_DEFAULT,
+                rule_id=f"defaults:{default.selector}",
+                rule_reason=default.reason,
+                params=default.params,
+            )
+        behavior = Action(self.policy.document.settings.unknown_sensitive_behavior)
+        if confidence_miss:
+            reason = ReasonCode.CONFIDENCE_BELOW_RULE_THRESHOLD
+        elif behavior == Action.BLOCK:
+            reason = ReasonCode.NO_APPLICABLE_RULE_BLOCKS
+        else:
+            reason = ReasonCode.NO_APPLICABLE_RULE_REQUIRES_REVIEW
+        return Decision(action=behavior, reason_code=reason, level=LEVEL_FALLBACK)
+
+    def _apply_hard_constraints(
+        self, decision: Decision, finding: Finding, ctx: EffectiveContext, fmt: InputFormat
+    ) -> Decision:
+        if finding.category == CREDENTIAL_CATEGORY and (
+            decision.action not in CREDENTIAL_PERMITTED_ACTIONS
+        ):
+            return Decision(
+                Action.BLOCK,
+                ReasonCode.CREDENTIAL_DETECTED_HARD_BLOCK,
+                LEVEL_HARD_CONSTRAINT,
+                overridden_rule_id=decision.rule_id,
+            )
+        if decision.action == Action.ALLOW and finding.category in self.policy.high_risk:
+            untrusted = ctx.is_untrusted
+            rule = next((r for r in self.policy.rules if r.id == decision.rule_id), None)
+            acknowledged = rule is not None and rule.rule.acknowledge_risk
+            if untrusted and not acknowledged:
+                return Decision(
+                    Action.REVIEW,
+                    ReasonCode.HIGH_RISK_ALLOW_REQUIRES_ACKNOWLEDGEMENT,
+                    LEVEL_HARD_CONSTRAINT,
+                    overridden_rule_id=decision.rule_id,
+                )
+        unsupported = (decision.action == Action.DROP_FIELD and fmt in LINE_FORMATS) or (
+            finding.location.in_key and decision.action in VALUE_TRANSFORM_ACTIONS
+        )
+        if unsupported and finding.category == CREDENTIAL_CATEGORY:
+            # A credential that cannot be removed where it is must not wait for review.
+            return Decision(
+                Action.BLOCK,
+                ReasonCode.CREDENTIAL_DETECTED_HARD_BLOCK,
+                LEVEL_HARD_CONSTRAINT,
+                overridden_rule_id=decision.rule_id,
+            )
+        if unsupported:
+            return Decision(
+                Action.REVIEW,
+                ReasonCode.UNSUPPORTED_TRANSFORM,
+                LEVEL_HARD_CONSTRAINT,
+                overridden_rule_id=decision.rule_id,
+            )
+        return decision

ciphergate/policy/loader.py

@@ -0,0 +1,116 @@
+"""Safe YAML loading for policies.
+
+* Uses ``yaml.SafeLoader`` (no arbitrary tags, no object construction).
+* Rejects duplicate mapping keys (PyYAML silently keeps the last one by default).
+* Rejects anchors/aliases, which enable "billion laughs" expansion and make policies harder
+  to review.
+* Enforces a size limit before parsing.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any
+
+import yaml
+from yaml.events import AliasEvent
+from yaml.nodes import MappingNode, Node
+
+from ciphergate.errors import PolicyValidationError, ValidationIssue
+
+MAX_POLICY_BYTES = 1024 * 1024
+
+
+class _StrictSafeLoader(yaml.SafeLoader):
+    def compose_node(self, parent: Node | None, index: int) -> Node | None:
+        if self.check_event(AliasEvent):
+            event = self.peek_event()  # type: ignore[no-untyped-call]
+            line = event.start_mark.line + 1 if event.start_mark else 0
+            raise PolicyValidationError(
+                "YAML anchors/aliases are not allowed in policies",
+                issues=[ValidationIssue(f"line {line}", "alias not allowed", "yaml_alias")],
+                code="policy_yaml_alias",
+            )
+        node: Node | None = super().compose_node(parent, index)
+        return node
+
+    def construct_mapping(self, node: MappingNode, deep: bool = False) -> dict[Any, Any]:
+        seen: set[Any] = set()
+        for key_node, _ in node.value:
+            key = self.construct_object(key_node, deep=deep)
+            if not isinstance(key, str | int | bool | float) and key is not None:
+                raise PolicyValidationError(
+                    "policy mapping keys must be scalars",
+                    issues=[_issue_at(key_node, "non-scalar key", "yaml_key")],
+                )
+            if key in seen:
+                raise PolicyValidationError(
+                    "duplicate key in policy YAML",
+                    issues=[_issue_at(key_node, f"duplicate key '{key}'", "yaml_duplicate_key")],
+                    code="policy_duplicate_key",
+                )
+            seen.add(key)
+        return super().construct_mapping(node, deep=deep)
+
+
+def _issue_at(node: Node, message: str, code: str) -> ValidationIssue:
+    line = node.start_mark.line + 1 if node.start_mark else 0
+    return ValidationIssue(f"line {line}", message, code)
+
+
+def read_policy_bytes(path: str | Path) -> bytes:
+    p = Path(path)
+    try:
+        if not p.is_file():
+            raise PolicyValidationError(
+                "policy file not found or not a regular file", code="policy_not_found"
+            )
+        size = p.stat().st_size
+        if size > MAX_POLICY_BYTES:
+            raise PolicyValidationError(
+                f"policy file exceeds {MAX_POLICY_BYTES} bytes", code="policy_too_large"
+            )
+        return p.read_bytes()
+    except OSError as exc:
+        raise PolicyValidationError(
+            "policy file could not be read", code="policy_unreadable"
+        ) from exc
+
+
+def parse_policy_yaml(data: bytes) -> dict[str, Any]:
+    """Parse YAML bytes into a plain mapping, with safe, value-free error messages."""
+    if len(data) > MAX_POLICY_BYTES:
+        raise PolicyValidationError("policy exceeds size limit", code="policy_too_large")
+    try:
+        text = data.decode("utf-8-sig")
+    except UnicodeDecodeError as exc:
+        raise PolicyValidationError(
+            "policy file is not valid UTF-8", code="policy_encoding"
+        ) from exc
+    try:
+        loaded = yaml.load(text, Loader=_StrictSafeLoader)  # noqa: S506 - strict SafeLoader subclass
+    except PolicyValidationError:
+        raise
+    except yaml.MarkedYAMLError as exc:
+        mark = exc.problem_mark
+        where = f"line {mark.line + 1}, column {mark.column + 1}" if mark else "unknown position"
+        raise PolicyValidationError(
+            "policy YAML syntax error",
+            issues=[ValidationIssue(where, "YAML syntax error", "yaml_syntax")],
+            code="policy_yaml_syntax",
+        ) from exc
+    except yaml.YAMLError as exc:
+        raise PolicyValidationError(
+            "policy YAML could not be parsed", code="policy_yaml_syntax"
+        ) from exc
+    if not isinstance(loaded, dict):
+        raise PolicyValidationError(
+            "policy document must be a YAML mapping", code="policy_not_mapping"
+        )
+    return loaded
+
+
+def policy_digest(data: bytes) -> str:
+    """Digest of the policy file contents. Policies reference keys by env-var name only."""
+    return "sha256:" + hashlib.sha256(data).hexdigest()