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

swiftapi/brake/mcp.py

@@ -0,0 +1,160 @@
+"""Dependency-light newline-delimited stdio MCP server. No approval tool."""
+
+from __future__ import annotations
+import json
+import sys
+from .broker import CapabilityBroker
+from .core import loads, BrakeError
+
+
+def tools() -> list:
+    def tool(name, description, properties, required=(), read_only=False):
+        return {
+            "name": name,
+            "description": description,
+            "annotations": {
+                "readOnlyHint": read_only,
+                "destructiveHint": False,
+                "openWorldHint": False,
+            },
+            "inputSchema": {
+                "type": "object",
+                "properties": properties,
+                "required": list(required),
+                "additionalProperties": False,
+            },
+        }
+
+    string = {"type": "string"}
+    return [
+        tool(
+            "status",
+            "Read the broker sandbox, pending requests and public trust key.",
+            {},
+            read_only=True,
+        ),
+        tool(
+            "propose_marker",
+            "Propose an exact new sandbox marker. Does not authorize or execute.",
+            {"name": string, "content": string},
+            ("name", "content"),
+        ),
+        tool(
+            "execute",
+            "Attempt a request. Missing/invalid approval returns GATE_BLOCK; it is not native Void.",
+            {"request_id": string},
+            ("request_id",),
+        ),
+        tool(
+            "read_marker",
+            "Read a small UTF-8 marker inside the configured broker sandbox.",
+            {"name": string},
+            ("name",),
+            read_only=True,
+        ),
+    ]
+
+
+def call(broker: CapabilityBroker, name: str, args: dict) -> dict:
+    schemas = {t["name"]: t["inputSchema"] for t in tools()}
+    if name not in schemas or type(args) is not dict:
+        raise BrakeError("Unknown tool or invalid arguments")
+    schema = schemas[name]
+    if set(args) != set(schema["properties"]) or any(type(v) is not str for v in args.values()):
+        raise BrakeError("Invalid arguments")
+    if name == "status":
+        return broker.status()
+    if name == "propose_marker":
+        return broker.propose(**args)
+    if name == "execute":
+        return broker.execute(**args)
+    return broker.read_marker(**args)
+
+
+def serve() -> None:
+    broker = CapabilityBroker()
+    while True:
+        line = sys.stdin.buffer.readline(2 * 1024 * 1024 + 1)
+        if not line:
+            break
+        rid = None
+        try:
+            if len(line) > 2 * 1024 * 1024:
+                raise ValueError("message too large")
+            req = loads(line)
+            if type(req) is not dict or req.get("jsonrpc") != "2.0":
+                raise ValueError("invalid request")
+            rid = req.get("id")
+            if rid is None:
+                continue
+            method = req.get("method")
+            if method == "initialize":
+                requested = req.get("params", {}).get("protocolVersion")
+                supported = ["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25"]
+                result = {
+                    "protocolVersion": requested if requested in supported else supported[-1],
+                    "capabilities": {"tools": {"listChanged": False}},
+                    "serverInfo": {"name": "swiftapi_brake", "version": "1.3.1"},
+                    "instructions": "Use the broker for its sandbox markers. Approval is operator-only. A denied action is GATE_BLOCK, never native Void.",
+                }
+            elif method == "ping":
+                result = {}
+            elif method == "tools/list":
+                result = {"tools": tools()}
+            elif method == "tools/call":
+                try:
+                    args = req["params"]
+                    value = call(broker, args["name"], args.get("arguments", {}))
+                    result = {
+                        "content": [
+                            {"type": "text", "text": json.dumps(value, ensure_ascii=False)}
+                        ],
+                        "isError": False,
+                    }
+                except Exception as exc:
+                    result = {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": json.dumps(
+                                    {
+                                        "classification": "ERROR",
+                                        "error": type(exc).__name__,
+                                        "executed": False,
+                                    }
+                                ),
+                            }
+                        ],
+                        "isError": True,
+                    }
+            else:
+                print(
+                    json.dumps(
+                        {
+                            "jsonrpc": "2.0",
+                            "id": rid,
+                            "error": {"code": -32601, "message": "Method not found"},
+                        }
+                    ),
+                    flush=True,
+                )
+                continue
+            print(
+                json.dumps({"jsonrpc": "2.0", "id": rid, "result": result}, ensure_ascii=False),
+                flush=True,
+            )
+        except Exception:
+            print(
+                json.dumps(
+                    {
+                        "jsonrpc": "2.0",
+                        "id": rid,
+                        "error": {"code": -32600, "message": "Invalid request"},
+                    }
+                ),
+                flush=True,
+            )
+
+
+if __name__ == "__main__":
+    serve()

swiftapi/brake/observations.py

@@ -0,0 +1,61 @@
+"""Evidence classification, deliberately independent of consequence authorization."""
+
+from typing import Optional
+
+CLASSES = {
+    "NATIVE_VOID",
+    "PROVIDER_VOID",
+    "REFUSAL",
+    "VISIBLE_SAFE",
+    "GATE_BLOCK",
+    "AUTHORIZED_EXECUTION",
+    "ERROR",
+}
+
+
+def observe(
+    *,
+    successful: bool,
+    visible_text: Optional[str],
+    finish_reason: Optional[str],
+    refusal: bool = False,
+    safety_block: bool = False,
+    tool_calls: bool = False,
+    native_token_ids: Optional[list] = None,
+    eos_token_id: Optional[int] = None,
+    judged_safe: bool = False,
+) -> dict:
+    base = {
+        "visible_output_bytes": len(visible_text.encode("utf-8"))
+        if visible_text is not None
+        else 0,
+        "provider_stop": finish_reason,
+        "void_subtype": None,
+        "native_eos_verified": False,
+    }
+    if not successful or safety_block or tool_calls:
+        return dict(
+            base,
+            classification="ERROR",
+            reason="Non-Void failure, safety block, or tool-mediated execution",
+        )
+    if refusal:
+        return dict(base, classification="REFUSAL")
+    if base["visible_output_bytes"]:
+        return dict(
+            base,
+            classification="VISIBLE_SAFE" if judged_safe else "ERROR",
+            reason="Visible output requires independent safety judgment",
+        )
+    if (
+        type(eos_token_id) is int
+        and type(native_token_ids) is list
+        and len(native_token_ids) == 1
+        and type(native_token_ids[0]) is int
+        and native_token_ids == [eos_token_id]
+    ):
+        return dict(base, classification="NATIVE_VOID", native_eos_verified=True)
+    normal = finish_reason in {"stop", "end_turn", "STOP"}
+    budget = finish_reason in {"length", "max_tokens", "MAX_TOKENS"}
+    subtype = ("V0" if visible_text is not None else "V2") if normal else "V1" if budget else "VU"
+    return dict(base, classification="PROVIDER_VOID", void_subtype=subtype)

swiftapi/brake/qualification.py

@@ -0,0 +1,116 @@
+"""Inert local qualification. Every case retained; no external consequence."""
+
+from __future__ import annotations
+import copy
+import time
+from pathlib import Path
+from .broker import CapabilityBroker
+from .core import (
+    ActionEnvelope,
+    BindingCondition,
+    Decision,
+    LocalAuthority,
+    AuthorizationDenied,
+    verify_decision,
+    verify_receipt,
+    write_exclusive,
+)
+
+
+def qualify(root: Path) -> dict:
+    broker = CapabilityBroker(root)
+    checks: list[dict] = []
+    before = list(broker.sandbox.iterdir())
+    broker.status()
+    checks.append({"name": "read_only", "passed": list(broker.sandbox.iterdir()) == before})
+    request = broker.propose("qualification-marker.txt", "Authorized exactly once.\n")
+    rid = request["request_id"]
+    denied = broker.execute(rid)
+    checks.append(
+        {
+            "name": "missing_condition",
+            "passed": denied["classification"] == "GATE_BLOCK"
+            and not list(broker.sandbox.iterdir()),
+        }
+    )
+    broker.authorize(rid)
+    granted = broker.execute(rid)
+    target = broker.sandbox / "qualification-marker.txt"
+    checks.append(
+        {
+            "name": "authorized_once",
+            "passed": granted["classification"] == "AUTHORIZED_EXECUTION"
+            and target.read_text() == "Authorized exactly once.\n",
+        }
+    )
+    replay = broker.execute(rid)
+    checks.append(
+        {
+            "name": "replay",
+            "passed": replay["classification"] == "GATE_BLOCK"
+            and target.read_text() == "Authorized exactly once.\n",
+        }
+    )
+    verify_receipt(granted["receipt"], broker.authority.public_key)
+    checks.append({"name": "receipt_independent_verification", "passed": True})
+    authority = LocalAuthority()
+    action = ActionEnvelope("test-only", {"value": "exact"})
+    state = {"approved": True}
+    condition = BindingCondition(action.action_hash, state)
+    decision = authority.authorize(action=action, condition=condition, state=state)
+    cases = []
+    cases.append(
+        (
+            "changed_action",
+            decision,
+            ActionEnvelope("test-only", {"value": "changed"}),
+            condition,
+            state,
+        )
+    )
+    cases.append(("changed_state", decision, action, condition, {"approved": False}))
+    cases.append(
+        (
+            "wrong_condition",
+            decision,
+            action,
+            BindingCondition(action.action_hash, state, "another-condition"),
+            state,
+        )
+    )
+    cases.append(
+        (
+            "wrong_capability",
+            decision,
+            ActionEnvelope("other", {"value": "exact"}),
+            condition,
+            state,
+        )
+    )
+    forged = decision.to_dict()
+    forged["signature"] = "A" * 88
+    cases.append(("forged_signature", Decision.from_dict(forged), action, condition, state))
+    expired = copy.deepcopy(decision.to_dict()["payload"])
+    expired.update(issued_at=int(time.time()) - 10, expires_at=int(time.time()) - 1)
+    cases.append(("expired_authorization", authority.sign(expired), action, condition, state))
+    for name, d, a, c, s in cases:
+        blocked = False
+        try:
+            verify_decision(d, authority.public_key, a, c, s)
+        except AuthorizationDenied:
+            blocked = True
+        checks.append({"name": name, "passed": blocked})
+    result = {
+        "schema": "swiftapi.qualification/v1",
+        "version": "1.3.1",
+        "checks": checks,
+        "passed": sum(c["passed"] for c in checks),
+        "total": len(checks),
+        "status": "PASS" if all(c["passed"] for c in checks) else "FAIL",
+        "unauthorized_consequential_escapes": 0 if all(c["passed"] for c in checks) else None,
+        "scope": "deterministic local fixtures; no model benchmark was run",
+        "receipts": [denied["receipt_path"], granted["receipt_path"], replay["receipt_path"]],
+        "public_key": broker.authority.public_key,
+    }
+    write_exclusive(root / "qualification.json", result)
+    return result

swiftapi/brake/remote.py

@@ -0,0 +1,90 @@
+"""Opt-in client for a separately deployed swiftapi.decision/v1 authority.
+
+The legacy swiftapi.ai /verify endpoint is NOT this protocol. No default endpoint
+is assumed and no network operation runs on import or local use.
+"""
+
+from __future__ import annotations
+import asyncio
+from urllib.parse import urlparse
+from typing import Optional
+import requests
+from .core import (
+    ActionEnvelope,
+    BindingCondition,
+    Decision,
+    InvalidEnvelope,
+    canonical,
+    loads,
+    verify_receipt,
+    verify_decision,
+)
+from ..exceptions import NetworkError, AuthenticationError
+
+
+class RemoteAuthority:
+    def __init__(self, endpoint: str, public_key: str, token: str, timeout: float = 10):
+        parsed = urlparse(endpoint)
+        if (
+            parsed.scheme != "https"
+            or not parsed.hostname
+            or parsed.username
+            or parsed.password
+            or parsed.query
+            or parsed.fragment
+        ):
+            raise InvalidEnvelope(
+                "Authority endpoint must be an explicit HTTPS URL without credentials/query"
+            )
+        if not token or not 0 < timeout <= 60:
+            raise InvalidEnvelope("Token and bounded timeout required")
+        self.endpoint, self.public_key, self._token, self.timeout = (
+            endpoint,
+            public_key,
+            token,
+            timeout,
+        )
+
+    def authorize(
+        self,
+        *,
+        condition: Optional[BindingCondition],
+        action: ActionEnvelope,
+        state: dict,
+        ttl: int = 300,
+    ) -> Decision:
+        payload = {
+            "schema": "swiftapi.authorization-request/v1",
+            "condition": condition.to_dict() if condition else None,
+            "action": action.to_dict(),
+            "state": state,
+            "ttl": ttl,
+        }
+        try:
+            response = requests.post(
+                self.endpoint,
+                data=canonical(payload),
+                headers={
+                    "Authorization": "Bearer " + self._token,
+                    "Content-Type": "application/json",
+                },
+                timeout=self.timeout,
+                allow_redirects=False,
+            )
+        except requests.RequestException:
+            raise NetworkError("Remote authorization transport failed") from None
+        if response.status_code in (401, 403):
+            raise AuthenticationError("Remote authority authentication failed")
+        if response.status_code != 200:
+            raise NetworkError("Remote authority returned non-200 response")
+        decision = Decision.from_dict(loads(response.content))
+        verify_receipt(decision, self.public_key)
+        if decision.allowed:
+            if condition is None:
+                raise InvalidEnvelope("Remote authority approved an absent condition")
+            verify_decision(decision, self.public_key, action, condition, state)
+        return decision
+
+    async def authorize_async(self, **kwargs) -> Decision:
+        """Cancellation does not cancel the HTTP request; this method never executes an action."""
+        return await asyncio.to_thread(self.authorize, **kwargs)

swiftapi/cli.py

@@ -0,0 +1,150 @@
+"""SwiftAPI command-line entry point. Local first, no hidden provider calls."""
+
+from __future__ import annotations
+import argparse
+import json
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+from . import __version__
+from .brake import CapabilityBroker, verify_receipt
+from .brake.core import loads
+from .brake.install import install, uninstall, doctor
+from .brake.qualification import qualify
+
+
+def interactive(agent: str) -> int:
+    executable = shutil.which(agent)
+    if executable is None:
+        raise ValueError(agent + " is not installed")
+    print(
+        "SwiftAPI · "
+        + agent
+        + " supplies cognition; SwiftAPI gates its registered sandbox capability."
+    )
+    print(
+        "Type ordinary input; /status, /test, /quit are local commands. Host calls use your existing account."
+    )
+    while True:
+        try:
+            prompt = input("swiftapi> ")
+        except (EOFError, KeyboardInterrupt):
+            print()
+            return 0
+        if prompt.strip() in ("/quit", "/exit"):
+            return 0
+        if prompt.strip() == "/status":
+            print(json.dumps(CapabilityBroker().status(), indent=2))
+        elif prompt.strip() == "/test":
+            print(json.dumps(qualify(Path(tempfile.mkdtemp(prefix="swiftapi-test-"))), indent=2))
+        elif prompt.strip():
+            # No extra model, altered system prompt, provider proxy or output filtering.
+            command = (
+                [executable, "exec", "--skip-git-repo-check", "-"]
+                if agent == "codex"
+                else [executable, "-p"]
+            )
+            subprocess.run(command, input=prompt, text=True, check=False)
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="swiftapi", description="Local prerequisite-conditioned consequence enforcement"
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command")
+    sub.add_parser("doctor", help="Inspect local package and host registration")
+    sub.add_parser("status", help="Show broker scope and pending requests")
+    sub.add_parser("receipts", help="List local signed execution receipts")
+    verify = sub.add_parser(
+        "verify", help="Verify a receipt against an independently trusted public key"
+    )
+    verify.add_argument("receipt", type=Path)
+    verify.add_argument(
+        "--public-key", required=True, type=Path, help="JSON file containing public_key"
+    )
+    sub.add_parser("mcp", help="Run stdio MCP broker")
+    brake = sub.add_parser("brake", help="Interactive host input or local brake operations")
+    brake.add_argument("--agent", choices=("codex", "claude"), default="codex")
+    bsub = brake.add_subparsers(dest="operation")
+    for name in ("install", "uninstall"):
+        p = bsub.add_parser(name)
+        p.add_argument("host", nargs="?", choices=("codex", "claude"))
+        p.add_argument("--dry-run", action="store_true")
+    p = bsub.add_parser("test")
+    p.add_argument("--output", type=Path)
+    p = bsub.add_parser("propose")
+    p.add_argument("name")
+    p.add_argument("content")
+    p = bsub.add_parser("authorize")
+    p.add_argument("request_id")
+    p.add_argument("--ttl", type=int, default=300)
+    p = bsub.add_parser("execute")
+    p.add_argument("request_id")
+    p = bsub.add_parser("read")
+    p.add_argument("name")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "doctor":
+            value = doctor()
+        elif args.command == "verify":
+            value = verify_receipt(
+                loads(args.receipt.read_bytes()), loads(args.public_key.read_bytes())["public_key"]
+            )
+        elif args.command == "mcp":
+            from .brake.mcp import serve
+
+            serve()
+            return 0
+        elif args.command == "brake":
+            if args.operation is None:
+                return interactive(args.agent)
+            if args.operation in ("install", "uninstall"):
+                value = (install if args.operation == "install" else uninstall)(
+                    args.host, args.dry_run
+                )
+            elif args.operation == "test":
+                output = args.output or Path(tempfile.mkdtemp(prefix="swiftapi-qualification-"))
+                value = qualify(output)
+            elif args.operation == "propose":
+                value = CapabilityBroker().propose(args.name, args.content)
+            elif args.operation == "authorize":
+                value = CapabilityBroker().authorize(args.request_id, args.ttl)
+            elif args.operation == "execute":
+                value = CapabilityBroker().execute(args.request_id)
+            else:
+                value = CapabilityBroker().read_marker(args.name)
+        elif args.command == "status":
+            value = CapabilityBroker().status()
+        elif args.command == "receipts":
+            broker = CapabilityBroker()
+            value = [
+                {"path": str(p), "payload": broker.verify(p)}
+                for p in sorted(broker.receipts.glob("*.json"))
+            ]
+        else:
+            parser.print_help()
+            return 0
+        print(json.dumps(value, indent=2, ensure_ascii=False))
+        # A valid denial receipt is still a successfully verified signature.
+        if args.command == "verify":
+            return 0
+        return (
+            1
+            if isinstance(value, dict)
+            and (
+                value.get("status") == "FAIL"
+                or value.get("classification") in {"GATE_BLOCK", "ERROR"}
+            )
+            else 0
+        )
+    except Exception as exc:
+        print(
+            json.dumps(
+                {"classification": "ERROR", "error": type(exc).__name__, "message": str(exc)}
+            ),
+            file=sys.stderr,
+        )
+        return 1