bylaw-python 0.4.0__py3-none-any.whl

bylaw_python/manifest.py

@@ -0,0 +1,152 @@
+# Ledgix ALCV — Manifest Layer
+# Schema, loading, and pattern matching for config-driven auto-instrumentation.
+
+from __future__ import annotations
+
+import fnmatch
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+MANIFEST_FILENAMES = ("ledgix.yaml", "ledgix.yml", "ledgix.json")
+
+
+@dataclass(frozen=True)
+class ManifestRule:
+    """A single enforcement rule declared in the manifest.
+
+    Attributes:
+        tool: Glob pattern matched against function names (e.g. ``"stripe_*"``).
+        policy_id: Policy to enforce for matching tools.
+        context: Extra key/value pairs forwarded to the clearance request context.
+    """
+
+    tool: str
+    policy_id: str | None = None
+    context: dict[str, Any] = field(default_factory=dict)
+
+    def matches(self, name: str) -> bool:
+        """Return ``True`` if *name* matches this rule's glob pattern."""
+        return fnmatch.fnmatch(name, self.tool)
+
+
+@dataclass
+class Manifest:
+    """Parsed enforcement manifest.
+
+    Contains an ordered list of :class:`ManifestRule` objects.  Rules are
+    evaluated in declaration order — the first match wins.
+    """
+
+    rules: list[ManifestRule]
+    source: str = "<inline>"
+
+    def match(self, name: str) -> ManifestRule | None:
+        """Return the first rule whose pattern matches *name*, or ``None``."""
+        for rule in self.rules:
+            if rule.matches(name):
+                return rule
+        return None
+
+    def __repr__(self) -> str:
+        return f"Manifest(rules={len(self.rules)}, source={self.source!r})"
+
+
+def load_manifest(
+    source: str | Path | dict[str, Any] | None = None,
+) -> Manifest:
+    """Load an enforcement manifest from a file, an inline dict, or auto-discovery.
+
+    Supported file formats:
+
+    * **YAML** (``.yaml`` / ``.yml``) — requires ``pyyaml`` (``pip install pyyaml``
+      or ``pip install 'bylaw-python[yaml]'``)
+    * **JSON** (``.json``) — no extra dependencies
+
+    When *source* is ``None`` the function searches the current working
+    directory for ``ledgix.yaml``, ``ledgix.yml``, then ``ledgix.json`` in
+    that order.
+
+    Manifest schema::
+
+        enforce:
+          - tool: "stripe_*"
+            policy_id: "financial-high-risk"
+          - tool: "db_write*"
+            policy_id: "data-mutation"
+            context:
+              risk_level: "high"
+          - tool: "*"               # catch-all (optional)
+            policy_id: "default"
+
+    Args:
+        source: File path, inline ``dict``, or ``None`` for auto-discovery.
+
+    Returns:
+        Parsed :class:`Manifest`.
+
+    Raises:
+        FileNotFoundError: If *source* is ``None`` and no manifest file exists,
+            or if an explicit path does not exist.
+        ImportError: If a YAML file is given but ``pyyaml`` is not installed.
+        ValueError: If the file extension is not ``.yaml``, ``.yml``, or ``.json``.
+    """
+    if source is None:
+        path = _find_default_manifest()
+        data = _parse_file(path)
+        src_label = str(path)
+    elif isinstance(source, dict):
+        data = source
+        src_label = "<inline>"
+    else:
+        path = Path(source)
+        if not path.exists():
+            raise FileNotFoundError(f"Ledgix manifest not found: {path}")
+        data = _parse_file(path)
+        src_label = str(path)
+
+    rules = [
+        ManifestRule(
+            tool=entry["tool"],
+            policy_id=entry.get("policy_id"),
+            context=entry.get("context") or {},
+        )
+        for entry in data.get("enforce", [])
+    ]
+    return Manifest(rules=rules, source=src_label)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _find_default_manifest() -> Path:
+    cwd = Path.cwd()
+    for name in MANIFEST_FILENAMES:
+        candidate = cwd / name
+        if candidate.exists():
+            return candidate
+    raise FileNotFoundError(
+        "No Ledgix manifest found in the current directory. "
+        f"Create one of: {', '.join(MANIFEST_FILENAMES)}"
+    )
+
+
+def _parse_file(path: Path) -> dict[str, Any]:
+    if path.suffix in (".yaml", ".yml"):
+        try:
+            import yaml  # type: ignore[import-untyped]
+        except ImportError as exc:
+            raise ImportError(
+                "PyYAML is required to load YAML manifests. "
+                "Install it with: pip install pyyaml  "
+                "or: pip install 'bylaw-python[yaml]'"
+            ) from exc
+        return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    if path.suffix == ".json":
+        return json.loads(path.read_text(encoding="utf-8"))
+    raise ValueError(
+        f"Unsupported manifest format: {path.suffix!r}. "
+        "Use .yaml, .yml, or .json."
+    )

bylaw_python/models.py

@@ -0,0 +1,330 @@
+# Ledgix ALCV — Data Models
+# Pydantic models for Vault API request/response payloads
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, field_validator, model_validator
+
+_MISSING = object()
+
+
+class ClearanceRequest(BaseModel):
+    """Payload sent to the Vault's ``/request-clearance`` endpoint."""
+
+    tool_name: str = Field(..., description="Name of the tool the agent wants to invoke")
+    tool_args: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Arguments the agent will pass to the tool",
+    )
+    agent_id: str = Field(default="default-agent", description="Identifier for the calling agent")
+    session_id: str = Field(default="", description="Session grouping identifier")
+    context: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional context for the Vault's policy judge (e.g. conversation history)",
+    )
+    human_principal: str | None = Field(
+        default=None,
+        description="Advisory OIDC sub of the human on whose behalf the agent acts",
+    )
+    parent_jti: str | None = Field(
+        default=None,
+        description="JTI of the parent A-JWT; present on delegated sub-agent requests",
+    )
+    destination_uri: str | None = Field(
+        default=None,
+        description="Canonical URI the action will be sent to (e.g. https://api.openai.com/v1/chat/completions)",
+    )
+    destination_provider: str | None = Field(
+        default=None,
+        description="Canonical provider key (e.g. openai, stripe, anthropic, aws-bedrock)",
+    )
+    destination_account_ref: str | None = Field(
+        default=None,
+        description="Account/org/workspace ref within the provider (e.g. Stripe acct id, Slack team id)",
+    )
+    # Phase 2 — GDPR Article 30 processing-register matching.
+    # When supplied, the Vault's pre-LLM validator chain checks for an active
+    # processing register that covers (data_categories ⊇ requested,
+    # purpose ∈ register.purposes, recipient ∈ register.recipients). Unmatched
+    # requests are denied with reason_code='processing_no_register_match'.
+    data_categories: list[str] | None = Field(
+        default=None,
+        description="Personal-data categories this action will touch (e.g. ['customer_email','transaction_amount'])",
+    )
+    purpose: str | None = Field(
+        default=None,
+        description="Purpose of processing (e.g. 'fraud_detection', 'billing'); must be in matched register's purposes",
+    )
+    processing_register_ref: str | None = Field(
+        default=None,
+        description="Optional UUID hint of which register this action anchors to; Vault still does authoritative match",
+    )
+    # Phase 6 — dataset lineage. When supplied, dataset sheets auto-derive
+    # row counts, schema fingerprints, and consent-basis breakdowns from
+    # ledger replay scoped to events with this ref.
+    dataset_ref: str | None = Field(
+        default=None,
+        description="Logical dataset reference this action reads/writes (e.g. 'prod_customer_support_kb', S3 path, table name)",
+    )
+
+
+ConfidenceBucket = Literal["extra_high", "high", "medium", "low", "none"]
+DecisionStatus = Literal["approved", "denied", "approved_pending_review"]
+
+
+class ClearanceResponse(BaseModel):
+    """Response from the Vault's ``/request-clearance`` endpoint.
+
+    As of v1.0 the wire format is bucket-only. The legacy ``approved``,
+    ``confidence``, and ``minimum_confidence_score`` fields have been
+    removed; consumers read ``decision_status`` and ``confidence_bucket``
+    instead. See ``docs/MIGRATION_0.4.md`` for the migration guide.
+    """
+
+    status: str = Field(default="denied", description="Vault lifecycle: processing, approved, denied, or pending_review")
+    decision_status: DecisionStatus = Field(
+        default="denied",
+        description="Categorical decision: approved | denied | approved_pending_review",
+    )
+    requires_manual_review: bool = Field(default=False, description="Whether the request is pending human review")
+    token: str | None = Field(default=None, description="Signed A-JWT if approved, None if denied")
+    reason: str = Field(default="", description="Human-readable explanation of the decision")
+    request_id: str = Field(default="", description="Vault-assigned unique ID for this request")
+    confidence_bucket: ConfidenceBucket = Field(
+        default="none",
+        description="Categorical confidence: extra_high | high | medium | low | none",
+    )
+    minimum_confidence_bucket: ConfidenceBucket = Field(
+        default="high",
+        description="Client-configured minimum confidence bucket for auto approval",
+    )
+    policy_version_id: str | None = Field(
+        default=None,
+        description="UUID of the policy version the decision was evaluated against",
+    )
+    policy_content_hash: str | None = Field(
+        default=None,
+        description="Content hash of the policy version the decision was evaluated against",
+    )
+    reason_code: str | None = Field(
+        default=None,
+        description="Machine-readable denial code, e.g. 'spend_cap_exceeded'",
+    )
+
+    @property
+    def is_approved(self) -> bool:
+        """Convenience: True iff the policy permits the action.
+
+        Returns True for both ``approved`` and ``approved_pending_review``.
+        Use this in place of the legacy ``approved`` boolean. Note that
+        ``approved_pending_review`` does NOT mean the agent can proceed
+        immediately — it means the policy permits the action subject to
+        human review.
+        """
+        return self.decision_status in ("approved", "approved_pending_review")
+
+
+class PolicyRegistration(BaseModel):
+    """Payload for registering a policy with the Vault."""
+
+    policy_id: str = Field(..., description="Unique identifier for the policy")
+    description: str = Field(default="", description="Human-readable description of the policy")
+    rules: list[str] = Field(
+        default_factory=list,
+        description="List of plain-English rules (e.g. 'Refunds must not exceed $100')",
+    )
+    tools: list[str] = Field(
+        default_factory=list,
+        description="Tool names this policy applies to (empty = all tools)",
+    )
+
+
+class PolicyRegistrationResponse(BaseModel):
+    """Response from the Vault's ``/register-policy`` endpoint."""
+
+    policy_id: str = Field(..., description="Confirmed policy ID")
+    status: str = Field(default="registered", description="Registration status")
+    message: str = Field(default="", description="Additional information")
+
+
+class LedgerEntry(BaseModel):
+    """Ledger entry returned by the Vault's ledger endpoints."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    seq: int
+    event_uuid: str
+    request_id: str
+    agent_id: str = ""
+    policy_id: str = ""
+    policy_version_id: str = ""
+    policy_content_hash: str = ""
+    intent_hash: str = ""
+    tool_name: str
+    tool_args: dict[str, Any] = Field(default_factory=dict)
+    raw_tool_args: Any = Field(default_factory=lambda: _MISSING, exclude=True)
+    action_category: str = ""
+    action_metadata: dict[str, Any] = Field(default_factory=dict)
+    raw_action_metadata: Any = Field(default_factory=lambda: _MISSING, exclude=True)
+    reason: str = ""
+    citations: list[dict[str, Any]] = Field(default_factory=list)
+    raw_citations: Any = Field(default_factory=lambda: _MISSING, exclude=True)
+    evidence_chunks: list[dict[str, Any]] = Field(default_factory=list)
+    raw_evidence_chunks: Any = Field(default_factory=lambda: _MISSING, exclude=True)
+    # Legacy float kept for canonical_version=1 hash verification of old rows.
+    # New rows under canonical_version=2 also carry confidence_bucket and
+    # decision_status as their canonical signal.
+    confidence: float = Field(default=0.0, ge=0.0, le=1.0, description="Legacy bucket midpoint; prefer confidence_bucket")
+    confidence_bucket: ConfidenceBucket | None = Field(
+        default=None,
+        description="Categorical confidence; populated for canonical_version>=2 events",
+    )
+    decision_status: DecisionStatus | None = Field(
+        default=None,
+        description="Categorical decision; populated for canonical_version>=2 events",
+    )
+    approved: bool = Field(
+        default=False,
+        description="Legacy boolean; derived for new rows. Prefer decision_status.",
+    )
+    accepted_at: str = Field(validation_alias=AliasChoices("accepted_at", "decided_at"))
+    canonical_version: int = 1
+    event_hash: str
+    leaf_hash: str
+    leaf_index: int | None = None
+    checkpoint_id: int | None = None
+    receipt_algorithm: str = Field(
+        default="",
+        validation_alias=AliasChoices("receipt_algorithm", "signature_algorithm"),
+    )
+    receipt_key_id: str = Field(
+        default="",
+        validation_alias=AliasChoices("receipt_key_id", "signer_key_id"),
+    )
+    receipt_signature: str = Field(
+        default="",
+        validation_alias=AliasChoices("receipt_signature", "row_signature"),
+    )
+    receipt_payload: str = Field(default="")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _capture_raw_verification_fields(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        data = dict(value)
+        if "raw_tool_args" not in data and "tool_args" in data:
+            data["raw_tool_args"] = data.get("tool_args")
+        if "raw_action_metadata" not in data and "action_metadata" in data:
+            data["raw_action_metadata"] = data.get("action_metadata")
+        if "raw_citations" not in data and "citations" in data:
+            data["raw_citations"] = data.get("citations")
+        if "raw_evidence_chunks" not in data and "evidence_chunks" in data:
+            data["raw_evidence_chunks"] = data.get("evidence_chunks")
+        return data
+
+    @field_validator("tool_args", "action_metadata", mode="before")
+    @classmethod
+    def _normalize_nullable_dicts(cls, value: Any) -> Any:
+        if value is None:
+            return {}
+        return value
+
+    @field_validator("citations", "evidence_chunks", mode="before")
+    @classmethod
+    def _normalize_nullable_lists(cls, value: Any) -> Any:
+        if value is None:
+            return []
+        return value
+
+
+class LedgerCheckpoint(BaseModel):
+    """Signed checkpoint returned by the Vault."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    checkpoint_id: int
+    microblock_id: int = 0
+    tree_size: int
+    root_hash: str = Field(validation_alias=AliasChoices("root_hash", "head_row_hash"))
+    checkpoint_hash: str = Field(
+        validation_alias=AliasChoices("checkpoint_hash", "manifest_hash"),
+    )
+    prev_checkpoint_hash: str = Field(
+        default="",
+        validation_alias=AliasChoices("prev_checkpoint_hash", "prev_manifest_hash"),
+    )
+    signature_algorithm: str = Field(
+        default="",
+        validation_alias=AliasChoices("signature_algorithm", "signature_algorithm"),
+    )
+    signer_key_id: str = ""
+    checkpoint_signature: str = Field(
+        default="",
+        validation_alias=AliasChoices("checkpoint_signature", "manifest_signature"),
+    )
+    checkpoint_payload: str = Field(
+        default="",
+        validation_alias=AliasChoices("checkpoint_payload", "manifest_payload"),
+    )
+    signed_at: str = Field(validation_alias=AliasChoices("signed_at", "generated_at", "period_start"))
+    mmd_seconds: int = 30
+    export_target: str = ""
+    export_uri: str = ""
+    export_status: str = ""
+    exported_at: str | None = None
+
+
+LedgerManifest = LedgerCheckpoint
+
+
+class LedgerKeyVersion(BaseModel):
+    key_id: str
+    algorithm: str
+    public_jwk: str = ""
+    active_from: str
+    retired_at: str | None = None
+    attestation_payload: str = ""
+    attestation_signature: str = ""
+    attestation_key_id: str = ""
+    attestation_status: str = ""
+
+
+class InclusionProof(BaseModel):
+    event_uuid: str
+    request_id: str
+    event_hash: str
+    leaf_hash: str
+    leaf_index: int
+    tree_size: int
+    path: list[str] = Field(default_factory=list)
+    checkpoint: LedgerCheckpoint
+
+
+class ConsistencyProof(BaseModel):
+    from_checkpoint: LedgerCheckpoint
+    to_checkpoint: LedgerCheckpoint
+    path: list[str] = Field(default_factory=list)
+
+
+class LedgerProofBundle(BaseModel):
+    event: LedgerEntry
+    inclusion: InclusionProof
+    consistency: ConsistencyProof | None = None
+    keys: list[LedgerKeyVersion] = Field(default_factory=list)
+
+
+class LedgerVerificationResult(BaseModel):
+    """Result of independent offline ledger verification."""
+
+    intact: bool
+    verified_entries: int
+    verified_checkpoints: int = 0
+    verified_manifests: int
+    latest_leaf_hash: str | None = None
+    latest_checkpoint_hash: str | None = None
+    latest_manifest_hash: str | None = None
+    coverage_note: str | None = None
+    error: str | None = None

bylaw_python/pending.py

@@ -0,0 +1,128 @@
+# Ledgix ALCV — PendingApproval
+# Handle for detached manual-review decisions
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .client import LedgixClient
+    from .models import ClearanceResponse
+
+
+class PendingApproval:
+    """Handle for a clearance request that entered ``pending_review`` status.
+
+    Obtained when ``review_mode="detach"`` is set on :class:`~bylaw_python.VaultConfig`
+    and the Vault returns a ``pending_review`` response.
+
+    Usage (async)::
+
+        try:
+            result = await client.arequest_clearance(request)
+        except ReviewPendingError as exc:
+            pending = exc.pending_approval
+            # store pending.request_id, come back later
+            result = await pending.wait_async(timeout=1800)
+
+    Usage (sync)::
+
+        try:
+            result = client.request_clearance(request)
+        except ReviewPendingError as exc:
+            result = exc.pending_approval.wait(timeout=1800)
+    """
+
+    def __init__(
+        self,
+        request_id: str,
+        client: "LedgixClient",
+        initial_response: "ClearanceResponse",
+    ) -> None:
+        self._request_id = request_id
+        self._client = client
+        self._initial_response = initial_response
+
+    @property
+    def request_id(self) -> str:
+        """The Vault's unique ID for this clearance request."""
+        return self._request_id
+
+    def wait(self, timeout: float | None = None) -> "ClearanceResponse":
+        """Block until the reviewer decides, then return the :class:`ClearanceResponse`.
+
+        Args:
+            timeout: Maximum seconds to wait. Defaults to the client's
+                ``review_timeout`` config value.
+
+        Raises:
+            ManualReviewTimeoutError: If no decision arrives within *timeout*.
+            ClearanceDeniedError: If the reviewer denies the request.
+        """
+        from .exceptions import ClearanceDeniedError, ManualReviewTimeoutError
+        from .models import ClearanceResponse as CR
+
+        deadline = time.monotonic() + (timeout if timeout is not None else self._client.config.review_timeout)
+        poll = self._client.config.review_poll_interval
+
+        while time.monotonic() < deadline:
+            time.sleep(poll)
+            response = self._client._get_sync_client().get(
+                f"/clearance-status/{self._request_id}"
+            )
+            response.raise_for_status()
+            clearance = CR.model_validate(response.json())
+            if clearance.status not in {"processing", "pending_review"}:
+                if not clearance.is_approved:
+                    raise ClearanceDeniedError(
+                        reason=clearance.reason,
+                        request_id=clearance.request_id,
+                    )
+                return clearance
+
+        raise ManualReviewTimeoutError(self._request_id)
+
+    async def wait_async(self, timeout: float | None = None) -> "ClearanceResponse":
+        """Async variant of :meth:`wait`."""
+        import asyncio
+
+        from .exceptions import ClearanceDeniedError, ManualReviewTimeoutError
+        from .models import ClearanceResponse as CR
+
+        deadline = time.monotonic() + (timeout if timeout is not None else self._client.config.review_timeout)
+        poll = self._client.config.review_poll_interval
+
+        while time.monotonic() < deadline:
+            await asyncio.sleep(poll)
+            response = await self._client._get_async_client().get(
+                f"/clearance-status/{self._request_id}"
+            )
+            response.raise_for_status()
+            clearance = CR.model_validate(response.json())
+            if clearance.status not in {"processing", "pending_review"}:
+                if not clearance.is_approved:
+                    raise ClearanceDeniedError(
+                        reason=clearance.reason,
+                        request_id=clearance.request_id,
+                    )
+                return clearance
+
+        raise ManualReviewTimeoutError(self._request_id)
+
+    def cancel(self) -> None:
+        """Cancel the pending review by posting a denial decision.
+
+        Records a ``review.cancelled_by_agent`` entry in the Vault ledger.
+        """
+        self._client._get_sync_client().post(
+            f"/reviews/{self._request_id}/decision",
+            json={"approved": False, "review_reason": "cancelled by agent"},
+        )
+
+    async def acancel(self) -> None:
+        """Async variant of :meth:`cancel`."""
+        await self._client._get_async_client().post(
+            f"/reviews/{self._request_id}/decision",
+            json={"approved": False, "review_reason": "cancelled by agent"},
+        )

bylaw_python/webhook.py

@@ -0,0 +1,44 @@
+# Ledgix ALCV — Webhook verification helper
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+def verify_webhook(body: bytes | str, signature: str, secret: str) -> bool:
+    """Verify the HMAC-SHA256 signature on an inbound Ledgix webhook.
+
+    The Vault signs every delivery with ``X-Ledgix-Signature: sha256=<hex>``.
+    Pass the raw request body, that header value, and your endpoint's signing
+    secret to verify authenticity before processing the event.
+
+    Args:
+        body: Raw request body (bytes or str).  Use the unparsed body exactly
+            as received — do not re-encode from a parsed JSON object.
+        signature: Value of the ``X-Ledgix-Signature`` header.
+        secret: Signing secret for this webhook endpoint (from the dashboard).
+
+    Returns:
+        ``True`` if the signature is valid, ``False`` otherwise.
+
+    Example::
+
+        from flask import request
+        import bylaw_python as ledgix
+
+        @app.route("/webhook", methods=["POST"])
+        def handle_webhook():
+            if not ledgix.verify_webhook(request.data, request.headers["X-Ledgix-Signature"], SECRET):
+                return "Forbidden", 403
+            event = request.get_json()
+            ...
+    """
+    if isinstance(body, str):
+        body = body.encode("utf-8")
+
+    if signature.startswith("sha256="):
+        signature = signature[len("sha256="):]
+
+    expected = hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature)