swiftapi-python 1.2.2__py3-none-any.whl → 1.3.0__py3-none-any.whl

swiftapi/brake/__init__.py

@@ -0,0 +1,45 @@
+"""Local consequence enforcement; no model or cloud account required."""
+
+from .core import (
+    ActionEnvelope,
+    BindingCondition,
+    ContinuationAuthority,
+    Decision,
+    DecisionReceipt,
+    LocalAuthority,
+    LocalGuard,
+    ReplayLedger,
+    AuthorizationDenied,
+    ReplayError,
+    InvalidEnvelope,
+    BrakeError,
+    canonical,
+    digest,
+    verify_receipt,
+    verify_decision,
+)
+from .broker import CapabilityBroker
+
+__all__ = [
+    "ActionEnvelope",
+    "BindingCondition",
+    "ContinuationAuthority",
+    "Decision",
+    "DecisionReceipt",
+    "LocalAuthority",
+    "LocalGuard",
+    "ReplayLedger",
+    "AuthorizationDenied",
+    "ReplayError",
+    "InvalidEnvelope",
+    "BrakeError",
+    "canonical",
+    "digest",
+    "verify_receipt",
+    "verify_decision",
+    "CapabilityBroker",
+]
+
+from .remote import RemoteAuthority
+
+__all__ += ["RemoteAuthority"]

swiftapi/brake/benchmarks.py

@@ -0,0 +1,111 @@
+"""Import externally judged defensive evaluations without copying their corpora.
+
+Rows must carry immutable framework/corpus identities and explicit executor
+observations. This adapter does not infer safety, authority, or escape from text.
+"""
+
+from __future__ import annotations
+from collections import Counter
+from pathlib import Path
+from typing import Iterable
+from .core import InvalidEnvelope, digest, loads, write_exclusive
+from .observations import CLASSES
+
+FRAMEWORKS = {"JailbreakBench", "HarmBench", "StrongREJECT"}
+
+
+def summarize(rows: Iterable[dict], expected_ids: Iterable[str]) -> dict:
+    ids = list(expected_ids)
+    if not ids or len(ids) != len(set(ids)):
+        raise InvalidEnvelope("Expected unique nonempty benchmark case IDs")
+    results = list(rows)
+    seen = []
+    counts: Counter = Counter()
+    failures = []
+    for row in results:
+        required = {
+            "case_id",
+            "framework",
+            "revision",
+            "corpus_sha256",
+            "classification",
+            "authorized",
+            "consequence_observed",
+            "evidence_sha256",
+        }
+        if (
+            not required <= set(row)
+            or row["framework"] not in FRAMEWORKS
+            or row["classification"] not in CLASSES
+        ):
+            raise InvalidEnvelope("Missing framework, evidence or outcome fields")
+        for field, size in (("revision", 40), ("corpus_sha256", 64), ("evidence_sha256", 64)):
+            v = row[field]
+            if type(v) is not str or len(v) != size or any(c not in "0123456789abcdef" for c in v):
+                raise InvalidEnvelope("Immutable source and evidence hashes required")
+        if type(row["authorized"]) is not bool or type(row["consequence_observed"]) is not bool:
+            raise InvalidEnvelope("Explicit independent execution observations required")
+        seen.append(row["case_id"])
+        counts[row["classification"]] += 1
+        if row["consequence_observed"] and not row["authorized"]:
+            failures.append(row)
+    if len(seen) != len(set(seen)) or set(seen) != set(ids):
+        raise InvalidEnvelope("Missing, duplicate, or unexpected cases; denominator cannot change")
+    return {
+        "schema": "swiftapi.benchmark/v1",
+        "total": len(ids),
+        "counts": dict(counts),
+        "unauthorized_consequential_escapes": len(failures),
+        "status": "FAIL" if failures or counts["ERROR"] else "PASS",
+        "failures": failures,
+        "rows_sha256": digest(results),
+        "results": results,
+    }
+
+
+def import_results(source: Path, output: Path, expected_ids: list) -> dict:
+    """Preserve all supplied rows. Output must be new; failures remain regressions."""
+    rows = [loads(line) for line in source.read_bytes().splitlines() if line.strip()]
+    report = summarize(rows, expected_ids)
+    write_exclusive(output, report)
+    return report
+
+
+def load_cases(framework: str, corpus: Path, expected_sha256: str) -> list:
+    """Read original upstream CSV bytes after pin verification; never rewrite corpora."""
+    import csv
+    import hashlib
+    import io
+
+    if framework not in FRAMEWORKS:
+        raise InvalidEnvelope("Unknown framework")
+    raw = corpus.read_bytes()
+    if hashlib.sha256(raw).hexdigest() != expected_sha256:
+        raise InvalidEnvelope("Corpus hash mismatch")
+    rows = list(csv.DictReader(io.StringIO(raw.decode("utf-8-sig"))))
+    mappings = {
+        "JailbreakBench": ("Goal", "Behavior", "Category"),
+        "HarmBench": ("Behavior", "BehaviorID", "SemanticCategory"),
+        "StrongREJECT": ("forbidden_prompt", None, "category"),
+    }
+    prompt, identifier, category = mappings[framework]
+    result = []
+    for index, row in enumerate(rows):
+        if prompt not in row or category not in row or (identifier and identifier not in row):
+            raise InvalidEnvelope("Unexpected upstream corpus columns")
+        result.append(
+            {
+                "case_id": framework
+                + ":"
+                + corpus.stem
+                + ":"
+                + (row[identifier] if identifier else str(index)),
+                "prompt": row[prompt],
+                "context": row.get("ContextString", ""),
+                "category": row[category],
+                "corpus_sha256": expected_sha256,
+            }
+        )
+    if len({r["case_id"] for r in result}) != len(result):
+        raise InvalidEnvelope("Duplicate corpus IDs")
+    return result

swiftapi/brake/broker.py

@@ -0,0 +1,274 @@
+"""A narrow credential-owning capability broker, independent of host hooks.
+
+The bundled capability creates a NEW UTF-8 marker inside one configured sandbox.
+No arbitrary shell execution, overwrite, path traversal, or model calls.
+"""
+
+from __future__ import annotations
+import os
+import re
+from pathlib import Path
+from typing import Optional
+from .core import (
+    ActionEnvelope,
+    AuthorizationDenied,
+    BindingCondition,
+    Decision,
+    InvalidEnvelope,
+    LocalAuthority,
+    ReplayLedger,
+    digest,
+    loads,
+    secure_dir,
+    verify_decision,
+    verify_receipt,
+    write_exclusive,
+)
+
+
+class CapabilityBroker:
+    def __init__(self, root: Optional[Path] = None):
+        self.root = secure_dir(
+            Path(root or os.environ.get("SWIFTAPI_HOME", str(Path.home() / ".local/share/swiftapi")))
+        )
+        self.sandbox = secure_dir(self.root / "sandbox")
+        self.pending = secure_dir(self.root / "pending")
+        self.grants = secure_dir(self.root / "grants")
+        self.receipts = secure_dir(self.root / "receipts")
+        self.authority = LocalAuthority.load(self.root)
+        self.ledger = ReplayLedger(self.root)
+        key = self.root / "public-key.json"
+        if not key.exists():
+            try:
+                write_exclusive(key, {"public_key": self.authority.public_key})
+            except FileExistsError:
+                pass
+        if key.is_symlink() or loads(key.read_bytes()) != {"public_key": self.authority.public_key}:
+            raise InvalidEnvelope("Trust key changed")
+
+    def status(self) -> dict:
+        return {
+            "version": "1.3.0",
+            "scope": "write_marker in configured sandbox only",
+            "sandbox": str(self.sandbox),
+            "public_key_file": str(self.root / "public-key.json"),
+            "public_key": self.authority.public_key,
+            "pending": sorted(p.stem for p in self.pending.glob("*.json")),
+            "receipt_count": len(list(self.receipts.glob("*.json"))),
+            "native_eos_claim": False,
+        }
+
+    def _action(self, name: str, content: str) -> ActionEnvelope:
+        if type(name) is not str or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,99}", name):
+            raise InvalidEnvelope(
+                "Marker name must be a basename of 1..100 ASCII letters, digits, _, ., -"
+            )
+        if type(content) is not str or len(content.encode("utf-8")) > 4096:
+            raise InvalidEnvelope("Marker content must be UTF-8 text of at most 4096 bytes")
+        return ActionEnvelope(
+            "write_marker",
+            {"sandbox": str(self.sandbox), "name": name, "content": content},
+            "Create the exact marker once",
+        )
+
+    def _state(self, action: ActionEnvelope) -> dict:
+        p = action.to_dict()["params"]
+        if self._action(p["name"], p["content"]).to_dict() != action.to_dict():
+            raise InvalidEnvelope("Unregistered capability or sandbox")
+        if self.sandbox.is_symlink() or self.sandbox.resolve() != self.sandbox:
+            raise InvalidEnvelope("Sandbox alias rejected")
+        s = self.sandbox.stat()
+        target = self.sandbox / p["name"]
+        return {
+            "sandbox": str(self.sandbox),
+            "device": s.st_dev,
+            "inode": s.st_ino,
+            "target_absent": not os.path.lexists(str(target)),
+        }
+
+    def propose(self, name: str, content: str) -> dict:
+        action = self._action(name, content)
+        state = self._state(action)
+        if state["target_absent"] is not True:
+            raise AuthorizationDenied("Existing targets cannot be overwritten")
+        condition = BindingCondition(action.action_hash, state, "operator-authorized-new-marker")
+        obj = {"action": action.to_dict(), "condition": condition.to_dict()}
+        request_id = digest(obj)
+        path = self.pending / (request_id + ".json")
+        if not path.exists():
+            try:
+                write_exclusive(path, obj)
+            except FileExistsError:
+                pass
+        return {
+            "request_id": request_id,
+            **obj,
+            "authorized": (self.grants / (request_id + ".json")).exists(),
+            "next": "Operator: swiftapi brake authorize " + request_id,
+        }
+
+    def request(self, request_id: str) -> tuple:
+        if type(request_id) is not str or not re.fullmatch("[a-f0-9]{64}", request_id):
+            raise InvalidEnvelope("Invalid request ID")
+        path = self.pending / (request_id + ".json")
+        if path.is_symlink():
+            raise InvalidEnvelope("Request alias rejected")
+        obj = loads(path.read_bytes())
+        if digest(obj) != request_id:
+            raise AuthorizationDenied("Request bytes changed")
+        action = ActionEnvelope(**obj["action"])
+        condition = BindingCondition(**obj["condition"])
+        self._state(action)
+        return action, condition
+
+    def authorize(self, request_id: str, ttl: int = 300) -> dict:
+        """Operator/application entry point. Deliberately absent from MCP tools."""
+        action, condition = self.request(request_id)
+        state = self._state(action)
+        decision = self.authority.authorize(
+            condition=condition, action=action, state=state, ttl=ttl
+        )
+        verify_decision(decision, self.authority.public_key, action, condition, state)
+        # Never replace a consumed/expired grant. A request has at most one grant.
+        write_exclusive(self.grants / (request_id + ".json"), decision.to_dict())
+        return {
+            "request_id": request_id,
+            "decision": decision.to_dict(),
+            "classification": "VISIBLE_SAFE",
+            "executed": False,
+        }
+
+    def _receipt(
+        self,
+        classification: str,
+        request_id: str,
+        action: Optional[ActionEnvelope],
+        decision: Optional[Decision],
+        phase: str,
+        reason: str,
+        executed: bool,
+    ) -> dict:
+        import secrets
+        import time
+
+        payload: dict = {
+            "schema": "swiftapi.execution/v1",
+            "issuer": self.authority.public_key,
+            "receipt_id": secrets.token_hex(32),
+            "created_at": int(time.time()),
+            "classification": classification,
+            "phase": phase,
+            "request_id": request_id,
+            "action_hash": action.action_hash if action else None,
+            "decision_hash": digest(decision.to_dict()) if decision else None,
+            "executed": executed,
+            "reason": reason,
+        }
+        receipt = self.authority.sign(payload)
+        path = self.receipts / (payload["receipt_id"] + ".json")
+        write_exclusive(path, receipt.to_dict())
+        return {
+            "classification": classification,
+            "executed": executed,
+            "receipt_path": str(path),
+            "receipt": receipt.to_dict(),
+        }
+
+    def execute(self, request_id: str) -> dict:
+        action = decision = None
+        try:
+            action, condition = self.request(request_id)
+            grant_path = self.grants / (request_id + ".json")
+            if grant_path.is_symlink():
+                raise AuthorizationDenied("Grant alias rejected")
+            decision = Decision.from_dict(loads(grant_path.read_bytes()))
+            state = self._state(action)
+            p = verify_decision(decision, self.authority.public_key, action, condition, state)
+            self.ledger.claim(p["issuer"], p["nonce"])
+        except (AuthorizationDenied, InvalidEnvelope, FileNotFoundError) as exc:
+            return self._receipt(
+                "GATE_BLOCK",
+                request_id,
+                action,
+                decision,
+                "authorization",
+                type(exc).__name__,
+                False,
+            )
+        # Persist authorization intent before executing. Any persistence failure aborts.
+        self._receipt(
+            "VISIBLE_SAFE",
+            request_id,
+            action,
+            decision,
+            "authorized_intent",
+            "verified; execution has not started",
+            False,
+        )
+        params = action.to_dict()["params"]
+        fd = None
+        try:
+            if self._state(action) != state:
+                raise AuthorizationDenied("State changed at execution boundary")
+            directory = os.open(str(self.sandbox), os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+            try:
+                st = os.fstat(directory)
+                if (st.st_dev, st.st_ino) != (state["device"], state["inode"]):
+                    raise AuthorizationDenied("Sandbox identity changed")
+                fd = os.open(
+                    params["name"],
+                    os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+                    0o600,
+                    dir_fd=directory,
+                )
+                with os.fdopen(fd, "wb") as stream:
+                    fd = None
+                    stream.write(params["content"].encode("utf-8"))
+                    stream.flush()
+                    os.fsync(stream.fileno())
+                os.fsync(directory)
+            finally:
+                os.close(directory)
+        except Exception as exc:
+            if fd is not None:
+                os.close(fd)
+            # May contain a partial write; never retry or claim no consequence.
+            return self._receipt(
+                "ERROR",
+                request_id,
+                action,
+                decision,
+                "execution",
+                type(exc).__name__ + "; inspect sandbox; do not retry",
+                False,
+            )
+        return self._receipt(
+            "AUTHORIZED_EXECUTION",
+            request_id,
+            action,
+            decision,
+            "execution",
+            "exact new marker written",
+            True,
+        )
+
+    def read_marker(self, name: str) -> dict:
+        action = self._action(name, "")
+        self._state(action)
+        directory = os.open(str(self.sandbox), os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+        try:
+            fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=directory)
+            with os.fdopen(fd, "rb") as f:
+                import stat
+
+                if not stat.S_ISREG(os.fstat(f.fileno()).st_mode):
+                    raise InvalidEnvelope("Not a regular marker")
+                data = f.read(4097)
+        finally:
+            os.close(directory)
+        if len(data) > 4096:
+            raise InvalidEnvelope("Marker exceeds limit")
+        return {"classification": "VISIBLE_SAFE", "name": name, "content": data.decode("utf-8")}
+
+    def verify(self, path: Path) -> dict:
+        return verify_receipt(loads(path.read_bytes()), self.authority.public_key)