cofferdam 0.0.0__py3-none-any.whl

cofferdam/__init__.py

@@ -0,0 +1,45 @@
+"""cofferdam — block outbound side effects from non-production environments.
+
+A plain Python library that makes a local TOML policy file — not the restored
+database — the authority over which outbound side effects (vendor API calls,
+email, payments, webhooks, report delivery, file transfer) are permitted in the
+current environment.
+
+Design rule: *Restored data owns business intent. Local environment config owns
+execution authority.* The engine fails closed. See ``docs/`` for the full
+requirements specification and ``docs/adr/`` for architecture decisions.
+
+Frappe/ERPNext integration is handled by the companion app ``cofferdam-app``
+(ADR-0012). This package has no Frappe dependency at any layer.
+"""
+
+from __future__ import annotations
+
+from cofferdam.config import load_policy, loads_policy
+from cofferdam.decisions import Decision
+from cofferdam.errors import (
+    CofferdamError,
+    CredentialError,
+    PolicyDeniedError,
+    PolicyFileNotFoundError,
+    PolicyValidationError,
+    SecretResolutionError,
+)
+from cofferdam.models import Environment, Policy, SideEffectKind
+
+__all__ = [
+    "CofferdamError",
+    "CredentialError",
+    "Decision",
+    "Environment",
+    "Policy",
+    "PolicyDeniedError",
+    "PolicyFileNotFoundError",
+    "PolicyValidationError",
+    "SecretResolutionError",
+    "SideEffectKind",
+    "load_policy",
+    "loads_policy",
+]
+
+__version__ = "0.1.0"

cofferdam/cli.py

@@ -0,0 +1,138 @@
+"""Command-line interface for cofferdam (BR-CLI-*).
+
+Provides three commands over a local policy file:
+
+    cofferdam validate PATH
+    cofferdam inspect  PATH
+    cofferdam decide   PATH --integration ... --kind ... --operation ... \\
+                            --method ... --url ... --credential ...
+
+``validate`` exits non-zero on an invalid policy. ``inspect`` prints a redacted
+summary. ``decide`` prints allow/deny and a reason code. No command ever prints a
+secret value (BR-CLI-004). Uses the stdlib ``argparse`` to keep the core
+dependency-free.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from cofferdam.config import load_policy
+from cofferdam.decisions import decide
+from cofferdam.errors import CofferdamError
+from cofferdam.http import host_from_url
+
+EXIT_OK = 0
+EXIT_DENIED = 1
+EXIT_INVALID = 2
+EXIT_USAGE = 3
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    try:
+        load_policy(args.path, strict=args.strict)
+    except CofferdamError as exc:
+        print(f"INVALID: {exc}", file=sys.stderr)
+        for problem in getattr(exc, "problems", []) or []:
+            print(f"  - {problem}", file=sys.stderr)
+        return EXIT_INVALID
+    print(f"OK: {args.path} is a valid policy")
+    return EXIT_OK
+
+
+def _cmd_inspect(args: argparse.Namespace) -> int:
+    try:
+        policy = load_policy(args.path)
+    except CofferdamError as exc:
+        print(f"INVALID: {exc}", file=sys.stderr)
+        return EXIT_INVALID
+
+    print(f"environment       : {policy.environment.value}")
+    print(f"default_decision  : {policy.default_decision.value}")
+    if policy.mail is not None:
+        print(f"mail.mode         : {policy.mail.mode}")
+    print(f"integrations      : {len(policy.integrations)}")
+    for name, integ in sorted(policy.integrations.items()):
+        state = "enabled" if integ.enabled else "disabled"
+        hosts = ", ".join(integ.allowed_hosts) or "(none)"
+        print(f"  - {name} [{integ.kind.value}, {state}] hosts: {hosts}")
+    print(f"credentials       : {len(policy.credentials)}")
+    for name, cred in sorted(policy.credentials.items()):
+        # Redacted: show the source *name*, never a value (BR-CLI-004).
+        source = f"env:{cred.secret_env}" if cred.secret_env else "raw:<redacted>"
+        print(f"  - {name} [profile={cred.profile}, source={source}]")
+    return EXIT_OK
+
+
+def _cmd_decide(args: argparse.Namespace) -> int:
+    try:
+        policy = load_policy(args.path)
+    except CofferdamError as exc:
+        print(f"INVALID: {exc}", file=sys.stderr)
+        return EXIT_INVALID
+
+    host = host_from_url(args.url) if args.url else args.host
+    decision = decide(
+        policy,
+        integration=args.integration,
+        kind=args.kind,
+        operation=args.operation,
+        method=args.method,
+        host=host,
+        credential=args.credential,
+    )
+    verdict = "ALLOW" if decision.allowed else "DENY"
+    print(f"{verdict}  reason={decision.reason_code}")
+    if decision.detail:
+        print(f"  detail: {decision.detail}")
+    return EXIT_OK if decision.allowed else EXIT_DENIED
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cofferdam",
+        description="Guard non-Production Frappe/ERPNext outbound side effects.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_validate = sub.add_parser("validate", help="validate a policy file")
+    p_validate.add_argument("path")
+    p_validate.add_argument(
+        "--strict",
+        action="store_true",
+        help="also require secret_env vars to be set and reject raw secrets",
+    )
+    p_validate.set_defaults(func=_cmd_validate)
+
+    p_inspect = sub.add_parser("inspect", help="print a redacted policy summary")
+    p_inspect.add_argument("path")
+    p_inspect.set_defaults(func=_cmd_inspect)
+
+    p_decide = sub.add_parser("decide", help="simulate a policy decision")
+    p_decide.add_argument("path")
+    p_decide.add_argument("--integration", required=True)
+    p_decide.add_argument("--kind")
+    p_decide.add_argument("--operation")
+    p_decide.add_argument("--method")
+    p_decide.add_argument("--url", help="target URL; hostname is parsed structurally")
+    p_decide.add_argument("--host", help="target hostname (alternative to --url)")
+    p_decide.add_argument("--credential")
+    p_decide.set_defaults(func=_cmd_decide)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except CofferdamError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return EXIT_INVALID
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

cofferdam/config.py

@@ -0,0 +1,66 @@
+"""Load and parse TOML policy files (BR-CONFIG-*).
+
+Uses the standard-library ``tomllib`` on Python 3.11+ and the ``tomli`` backport
+on 3.10. Parsing produces a validated :class:`~cofferdam.models.Policy`; semantic
+checks that span multiple sections are applied by :mod:`cofferdam.validators`.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - exercised on 3.10 only
+    import tomli as tomllib
+
+from pydantic import ValidationError
+
+from cofferdam.errors import PolicyFileNotFoundError, PolicyValidationError
+from cofferdam.models import Policy
+
+
+def _build_policy(data: dict[str, Any], *, source: str, strict: bool) -> Policy:
+    try:
+        policy = Policy.model_validate(data)
+    except ValidationError as exc:
+        problems = [
+            f"{'.'.join(str(p) for p in err['loc'])}: {err['msg']}" for err in exc.errors()
+        ]
+        raise PolicyValidationError(
+            f"invalid policy schema in {source}", problems=problems
+        ) from exc
+
+    from cofferdam.validators import validate_policy
+
+    validate_policy(policy, strict=strict, source=source)
+    return policy
+
+
+def loads_policy(text: str, *, source: str = "<string>", strict: bool = False) -> Policy:
+    """Parse and validate a policy from a TOML string."""
+    try:
+        data = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise PolicyValidationError(f"malformed TOML in {source}: {exc}") from exc
+    return _build_policy(data, source=source, strict=strict)
+
+
+def load_policy(path: str | Path, *, strict: bool = False) -> Policy:
+    """Load, parse, and validate a policy from a filesystem path.
+
+    :param strict: when True, apply stricter semantic checks (for example,
+        verifying that every ``secret_env`` variable is set). Intended for the
+        ``cofferdam validate`` CLI and CI, not the hot path.
+    :raises PolicyFileNotFoundError: the file does not exist (fail-closed;
+        BR-DECISION-001).
+    :raises PolicyValidationError: the file is malformed or invalid.
+    """
+    p = Path(path)
+    try:
+        text = p.read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise PolicyFileNotFoundError(f"policy file not found: {p}") from exc
+    return loads_policy(text, source=str(p), strict=strict)

cofferdam/credentials.py

@@ -0,0 +1,51 @@
+"""Credential reference resolution (BR-SECRET-*).
+
+A credential names *where* a secret comes from — it is not the secret. In v1 the
+only supported source is an environment variable (``secret_env``). Raw inline
+secrets (``secret_value``) are rejected unless the caller explicitly opts in
+(ADR-0007). No function here logs, prints, or embeds a secret value in an
+exception message (BR-LOG-002).
+"""
+
+from __future__ import annotations
+
+import os
+
+from cofferdam.errors import CredentialError, SecretResolutionError
+from cofferdam.models import Policy
+
+
+def resolve_secret(policy: Policy, name: str, *, allow_raw: bool = False) -> str:
+    """Resolve the secret material for credential ``name``.
+
+    :param name: key into ``policy.credentials``.
+    :param allow_raw: when True, a raw ``secret_value`` may be returned. Defaults
+        to False so that inline secrets are refused (ADR-0007, BR-SECRET-003).
+    :raises CredentialError: the credential is undefined, or defines no usable
+        source, or uses a raw secret without opt-in.
+    :raises SecretResolutionError: ``secret_env`` names an unset variable.
+    """
+    cred = policy.credentials.get(name)
+    if cred is None:
+        raise CredentialError(f"credential {name!r} is not defined in the policy")
+
+    if cred.secret_env:
+        try:
+            return os.environ[cred.secret_env]
+        except KeyError:
+            raise SecretResolutionError(
+                f"credential {name!r} requires environment variable "
+                f"{cred.secret_env!r}, which is not set"
+            ) from None
+
+    if cred.secret_value is not None:
+        if not allow_raw:
+            raise CredentialError(
+                f"credential {name!r} uses a raw inline secret_value, which is "
+                f"rejected by default; pass allow_raw=True to permit it"
+            )
+        return cred.secret_value
+
+    raise CredentialError(
+        f"credential {name!r} defines no secret source (expected secret_env)"
+    )

cofferdam/decisions.py

@@ -0,0 +1,174 @@
+"""The allow/deny decision engine (BR-DECISION-*).
+
+The engine is **fail-closed** (ADR-0005): a side effect is allowed only when the
+policy *explicitly* permits every dimension the caller supplies. Any missing,
+disabled, mismatched, or empty-allowlist condition denies. Each decision carries
+a stable ``reason_code`` and a redacted, log-safe context (BR-LOG-001) that never
+includes a secret value (BR-LOG-002).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from cofferdam.errors import PolicyDeniedError
+from cofferdam.models import Policy, SideEffectKind
+
+
+def host_matches(host: str, allowed_hosts: list[str]) -> bool:
+    """Return True iff ``host`` exactly matches an allowed hostname.
+
+    Comparison is case-insensitive and matches whole hostnames only, never
+    substrings, so ``sandbox.vendor.com`` never authorizes
+    ``sandbox.vendor.com.evil.example`` (BR-HOST-001). Extraction of a hostname
+    from a full URL is the caller's responsibility (see :mod:`cofferdam.http`).
+    """
+    needle = host.strip().rstrip(".").lower()
+    if not needle:
+        return False
+    return any(needle == allowed.strip().rstrip(".").lower() for allowed in allowed_hosts)
+
+
+@dataclass(frozen=True)
+class Decision:
+    """The structured outcome of a policy evaluation.
+
+    ``allowed`` is the verdict; ``reason_code`` is a stable machine-readable
+    token (e.g. ``"host_not_allowed"``). The remaining fields are log-safe
+    context. ``credential`` is the credential *reference name*, never its value.
+    """
+
+    allowed: bool
+    reason_code: str
+    environment: str | None = None
+    integration: str | None = None
+    kind: str | None = None
+    operation: str | None = None
+    method: str | None = None
+    host: str | None = None
+    credential: str | None = None
+    detail: str = ""
+
+    def as_log_dict(self) -> dict[str, object]:
+        """Return a redacted mapping suitable for structured logging (BR-LOG-001)."""
+        return {
+            "allowed": self.allowed,
+            "reason_code": self.reason_code,
+            "environment": self.environment,
+            "integration": self.integration,
+            "kind": self.kind,
+            "operation": self.operation,
+            "method": self.method,
+            "host": self.host,
+            "credential": self.credential,  # reference name only, never the secret
+            "detail": self.detail,
+        }
+
+    def message(self) -> str:
+        verb = "allowed" if self.allowed else "denied"
+        return (
+            f"outbound side effect {verb} "
+            f"[env={self.environment} integration={self.integration} "
+            f"kind={self.kind} operation={self.operation}] reason={self.reason_code}"
+            + (f": {self.detail}" if self.detail else "")
+        )
+
+    def to_exception(self) -> PolicyDeniedError:
+        """Build (but do not raise) a :class:`PolicyDeniedError` from this decision."""
+        return PolicyDeniedError(self)
+
+
+@dataclass(frozen=True)
+class _Ctx:
+    """Common evaluation context threaded into each Decision."""
+
+    environment: str
+    integration: str | None = None
+    kind: str | None = None
+    operation: str | None = None
+    method: str | None = None
+    host: str | None = None
+    credential: str | None = None
+
+    def deny(self, reason_code: str, detail: str = "") -> Decision:
+        return Decision(allowed=False, reason_code=reason_code, detail=detail, **vars(self))
+
+    def allow(self, reason_code: str = "explicitly_allowed", detail: str = "") -> Decision:
+        return Decision(allowed=True, reason_code=reason_code, detail=detail, **vars(self))
+
+
+def decide(
+    policy: Policy,
+    *,
+    integration: str,
+    kind: str | None = None,
+    operation: str | None = None,
+    method: str | None = None,
+    host: str | None = None,
+    credential: str | None = None,
+) -> Decision:
+    """Evaluate whether a single outbound side effect is permitted (BR-DECISION-001..010).
+
+    Only the dimensions the caller supplies are enforced, and each supplied
+    dimension must appear in the integration's explicit allowlist. An empty
+    allowlist denies (fail-closed). See ``docs/04-decision-engine.md``.
+    """
+    ctx = _Ctx(
+        environment=policy.environment.value,
+        integration=integration,
+        kind=kind,
+        operation=operation,
+        method=method,
+        host=host,
+        credential=credential,
+    )
+
+    integ = policy.integrations.get(integration)
+    if integ is None:
+        return ctx.deny("unknown_integration")
+    if not integ.enabled:
+        return ctx.deny("integration_disabled")
+
+    if kind is not None and integ.kind.value != kind:
+        return ctx.deny("kind_mismatch", f"policy declares kind={integ.kind.value}")
+
+    # Credential reference must exist and, if the integration pins one, must match.
+    if credential is not None:
+        if credential not in policy.credentials:
+            return ctx.deny("missing_credential")
+        if integ.credential is not None and integ.credential != credential:
+            return ctx.deny("credential_mismatch", f"integration requires {integ.credential!r}")
+
+    # Operation must be explicitly allowed when supplied (empty list denies).
+    if operation is not None and operation not in integ.allowed_operations:
+        return ctx.deny("operation_not_allowed")
+
+    # Payment-specific gates.
+    if integ.kind is SideEffectKind.PAYMENT:
+        if operation == "authorize" and not integ.allow_authorize:
+            return ctx.deny("payment_authorize_not_allowed")
+        if operation == "capture" and not integ.allow_capture:
+            return ctx.deny("payment_capture_not_allowed")
+
+    # HTTP method must be explicitly allowed when supplied (empty list denies).
+    if method is not None:
+        allowed_methods = {m.upper() for m in integ.allowed_methods}
+        if method.upper() not in allowed_methods:
+            return ctx.deny("method_not_allowed")
+
+    # Host must be explicitly allowed when supplied (empty list denies).
+    if host is not None and not host_matches(host, integ.allowed_hosts):
+        return ctx.deny("host_not_allowed")
+
+    return ctx.allow()
+
+
+def assert_allowed(policy: Policy, **kwargs: object) -> Decision:
+    """Evaluate a side effect and raise :class:`PolicyDeniedError` if denied.
+
+    Returns the allowing :class:`Decision` so callers may log it.
+    """
+    decision = decide(policy, **kwargs)  # type: ignore[arg-type]
+    if not decision.allowed:
+        raise decision.to_exception()
+    return decision

cofferdam/errors.py

@@ -0,0 +1,67 @@
+"""Explicit exception types for cofferdam.
+
+Implements the requirement that unsafe calls *fail closed with clear errors*
+(docs/01-overview.md, docs/04-decision-engine.md). Every exception carries
+enough structured context for server-side logging while guaranteeing that no
+secret value is ever placed in an exception message (BR-LOG-002).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from cofferdam.decisions import Decision
+
+
+class CofferdamError(Exception):
+    """Base class for every error raised by cofferdam."""
+
+
+class PolicyFileNotFoundError(CofferdamError):
+    """A policy file was expected on the local filesystem but not found.
+
+    Per BR-DECISION-001 this is a fail-closed condition: a missing policy file
+    denies all side effects unless the caller explicitly opted into a fallback.
+    """
+
+
+class PolicyValidationError(CofferdamError):
+    """A policy file is syntactically or semantically invalid.
+
+    Aggregates one or more human-readable problems. Distinguishes syntax errors
+    (malformed TOML) from semantic policy errors (BR-VALIDATE-011).
+    """
+
+    def __init__(self, message: str, *, problems: list[str] | None = None) -> None:
+        super().__init__(message)
+        self.problems: list[str] = problems or []
+
+
+class PolicyDeniedError(CofferdamError):
+    """Raised by ``assert_allowed`` when a side effect is not permitted.
+
+    Carries the originating :class:`~cofferdam.decisions.Decision` so callers and
+    logs can see the environment, integration, operation, and reason code — but
+    never a secret value.
+    """
+
+    def __init__(self, decision: Decision) -> None:
+        self.decision = decision
+        super().__init__(decision.message())
+
+
+class CredentialError(CofferdamError):
+    """A credential reference is missing, malformed, or mismatched.
+
+    Examples: an integration names a credential that the policy does not define,
+    or the credential's ``profile`` does not match what the integration requires.
+    """
+
+
+class SecretResolutionError(CredentialError):
+    """A credential is defined but its secret material could not be resolved.
+
+    Example: ``secret_env`` names an environment variable that is unset. The
+    missing variable name may appear in the message; the secret value never can.
+    """

cofferdam/http.py

@@ -0,0 +1,139 @@
+"""Policy-checked HTTP helper (BR-HTTP-*).
+
+This module wraps ``httpx`` and is only available when the optional dependency is
+installed (``pip install "cofferdam[http]"``, ADR-0008). The host parsed from the
+request URL is evaluated by the policy engine before any bytes or authorization
+headers are sent (BR-HOST-002, BR-HOST-004).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+from urllib.parse import urlsplit
+
+from cofferdam.decisions import decide
+from cofferdam.errors import CofferdamError
+
+if TYPE_CHECKING:
+    import httpx
+
+    from cofferdam.models import Policy
+
+_MAX_REDIRECTS = 10
+
+
+def _require_httpx() -> Any:
+    try:
+        import httpx
+    except ModuleNotFoundError as exc:  # pragma: no cover - trivial guard
+        raise CofferdamError(
+            "cofferdam.http requires the optional 'http' extra: "
+            'pip install "cofferdam[http]"'
+        ) from exc
+    return httpx
+
+
+def host_from_url(url: str) -> str:
+    """Extract the lowercase hostname from ``url`` using a structured parser.
+
+    Uses :func:`urllib.parse.urlsplit` so policy evaluation compares the real
+    hostname, never a substring of the raw URL (BR-HOST-001, BR-HOST-002).
+    """
+    host = urlsplit(url).hostname
+    if not host:
+        raise CofferdamError(f"could not parse a hostname from URL: {url!r}")
+    return host.lower()
+
+
+def request(
+    *,
+    policy: Policy,
+    integration: str,
+    operation: str,
+    method: str,
+    url: str,
+    credential: str | None = None,
+    follow_redirects: bool = False,
+    **kwargs: Any,
+) -> httpx.Response:
+    """Issue a policy-checked HTTP request.
+
+    Evaluates the policy — including the hostname from ``url`` — before any bytes
+    leave (BR-HOST-002, BR-HOST-004). When ``credential`` is supplied its resolved
+    secret is injected as ``Authorization: Bearer``. Redirects are not followed by
+    default (BR-HTTP-003); when enabled every redirect target is re-validated
+    before credentials are forwarded.
+    """
+    httpx_mod = _require_httpx()
+
+    host = host_from_url(url)
+    decision = decide(
+        policy,
+        integration=integration,
+        kind=None,
+        operation=operation,
+        method=method,
+        host=host,
+        credential=credential,
+    )
+    if not decision.allowed:
+        raise decision.to_exception()
+
+    # Resolve and inject credential as Authorization: Bearer (BR-SECRET-001, BR-HOST-004)
+    headers: dict[str, str] = {}
+    if credential is not None:
+        from cofferdam.credentials import resolve_secret
+
+        headers["Authorization"] = f"Bearer {resolve_secret(policy, credential)}"
+
+    # Merge caller-supplied headers; our Authorization takes precedence
+    if "headers" in kwargs:
+        merged: dict[str, str] = dict(kwargs.pop("headers"))
+        merged.update(headers)
+        headers = merged
+
+    if not follow_redirects:
+        return cast(
+            "httpx.Response",
+            httpx_mod.request(method, url, headers=headers, follow_redirects=False, **kwargs),
+        )
+
+    # Manual redirect loop: re-validate every hop before forwarding credentials (BR-HTTP-003)
+    body_keys = {"json", "data", "content", "files"}
+    body_kw: dict[str, Any] = {k: v for k, v in kwargs.items() if k in body_keys}
+    other_kw: dict[str, Any] = {k: v for k, v in kwargs.items() if k not in body_keys}
+    current_url = url
+    current_method = method
+
+    for _ in range(_MAX_REDIRECTS + 1):
+        response = httpx_mod.request(
+            current_method,
+            current_url,
+            headers=headers,
+            follow_redirects=False,
+            **body_kw,
+            **other_kw,
+        )
+        if not response.is_redirect:
+            return cast("httpx.Response", response)
+
+        redirect_url: str = cast(str, response.headers.get("location", ""))
+        redirect_host = host_from_url(redirect_url)
+        rd = decide(
+            policy,
+            integration=integration,
+            kind=None,
+            operation=operation,
+            method=current_method,
+            host=redirect_host,
+            credential=credential,
+        )
+        if not rd.allowed:
+            raise rd.to_exception()
+
+        current_url = redirect_url
+        if response.status_code in (301, 302, 303):
+            current_method = "GET"
+            body_kw = {}
+
+    raise CofferdamError(f"exceeded {_MAX_REDIRECTS} redirects")