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

swiftapi/verifier.py

@@ -1,130 +1,182 @@
-"""
-SwiftAPI SDK - Ed25519 Signature Verifier (The Shield)
-
-This module provides OFFLINE cryptographic verification of execution attestations.
-It does not require network connectivity - it uses the hardcoded SwiftAPI public key.
-"""
-
-import base64
-import json
-from datetime import datetime, timezone
-from typing import Dict, Any
-
-from nacl.signing import VerifyKey
-from nacl.exceptions import BadSignatureError
-
-from .exceptions import (
-    SignatureVerificationError,
-    AttestationExpiredError,
-)
-
-# SwiftAPI's Ed25519 Public Key (Base64)
-# This is the ONLY source of truth for attestation verification
-SWIFTAPI_PUBLIC_KEY_B64 = "jajZXZ0R3CUWkE5/5Mxx5Y76CdsSzaPDuT7aWnooZSk="
-
-# Decode public key once at module load
-SWIFTAPI_PUBLIC_KEY = base64.b64decode(SWIFTAPI_PUBLIC_KEY_B64)
-VERIFY_KEY = VerifyKey(SWIFTAPI_PUBLIC_KEY)
-
-
-def verify_signature(attestation: Dict[str, Any], ignore_expiry: bool = False) -> bool:
-    """
-    Verify the Ed25519 signature of an execution attestation.
-
-    This is OFFLINE verification - no network required.
-    The signature proves the attestation was issued by SwiftAPI.
-
-    Signature authenticity is permanent. Expiry is about the execution window,
-    not whether the attestation is genuine. Use ignore_expiry=True for audit
-    and post-hoc verification.
-
-    Args:
-        attestation: The execution_attestation dict from /verify response
-        ignore_expiry: If True, verify signature without checking expiry
-
-    Returns:
-        True if signature is valid
-
-    Raises:
-        SignatureVerificationError: If signature is invalid or missing
-        AttestationExpiredError: If attestation has expired (and ignore_expiry is False)
-    """
-    # Extract required fields
-    signature_b64 = attestation.get("signature")
-    if not signature_b64:
-        raise SignatureVerificationError("Missing signature in attestation")
-
-    jti = attestation.get("jti")
-    action_fingerprint = attestation.get("action_fingerprint")
-    expires_at = attestation.get("expires_at")
-
-    if not all([jti, action_fingerprint, expires_at]):
-        raise SignatureVerificationError("Incomplete attestation: missing required fields")
-
-    # Verify signature FIRST — authenticity is permanent
-    signed_payload = _reconstruct_signed_payload(attestation)
-
-    try:
-        signature = base64.b64decode(signature_b64)
-    except Exception as e:
-        raise SignatureVerificationError(f"Invalid signature encoding: {e}")
-
-    try:
-        VERIFY_KEY.verify(signed_payload, signature)
-    except BadSignatureError:
-        raise SignatureVerificationError(
-            "INVALID SIGNATURE: Attestation was not signed by SwiftAPI. "
-            "This could indicate a forged or tampered attestation."
-        )
-
-    # Check expiration AFTER signature (execution window, not authenticity)
-    if not ignore_expiry:
-        try:
-            expiry = datetime.fromisoformat(expires_at.replace("Z", "+00:00"))
-            now = datetime.now(timezone.utc)
-            if now > expiry:
-                raise AttestationExpiredError(f"Attestation expired at {expires_at}")
-        except ValueError as e:
-            raise SignatureVerificationError(f"Invalid expiration format: {e}")
-
-    return True
-
-
-def _reconstruct_signed_payload(attestation: Dict[str, Any]) -> bytes:
-    """
-    Reconstruct the exact payload that was signed by SwiftAPI.
-
-    The server signs the attestation BEFORE adding signature/signing_mode fields.
-    We must reconstruct that exact payload.
-    """
-    # Copy attestation and remove fields that weren't in the signed payload.
-    # signature/signing_mode are added after signing.
-    # action_data/denial_reason are added by /attest after signing.
-    _unsigned = ("signature", "signing_mode", "action_data", "denial_reason")
-    signed_fields = {k: v for k, v in attestation.items() if k not in _unsigned}
-
-    # Deterministic JSON serialization (must match server exactly)
-    payload_str = json.dumps(signed_fields, sort_keys=True, separators=(",", ":"))
-    return payload_str.encode("utf-8")
-
-
-def get_public_key() -> str:
-    """Return SwiftAPI's public key in Base64 format."""
-    return SWIFTAPI_PUBLIC_KEY_B64
-
-
-def is_valid(attestation: Dict[str, Any], ignore_expiry: bool = False) -> bool:
-    """
-    Check if attestation is valid without raising exceptions.
-
-    Args:
-        attestation: The execution_attestation dict
-        ignore_expiry: If True, only check signature authenticity
-
-    Returns:
-        True if valid, False otherwise
-    """
-    try:
-        return verify_signature(attestation, ignore_expiry=ignore_expiry)
-    except Exception:
-        return False
+"""
+SwiftAPI SDK - Ed25519 Signature Verifier (The Shield)
+
+This module provides OFFLINE cryptographic verification of execution attestations.
+It does not require network connectivity - it uses the hardcoded SwiftAPI public key.
+"""
+
+import base64
+import hashlib
+import json
+from datetime import datetime, timezone
+from typing import Dict, Any
+
+from nacl.signing import VerifyKey
+from nacl.exceptions import BadSignatureError
+
+from .exceptions import (
+    SignatureVerificationError,
+    AttestationExpiredError,
+    SwiftAPIError,
+)
+
+# SwiftAPI's Ed25519 Public Key (Base64)
+# This is the ONLY source of truth for attestation verification
+SWIFTAPI_PUBLIC_KEY_B64 = "jajZXZ0R3CUWkE5/5Mxx5Y76CdsSzaPDuT7aWnooZSk="
+
+# Decode public key once at module load
+SWIFTAPI_PUBLIC_KEY = base64.b64decode(SWIFTAPI_PUBLIC_KEY_B64)
+VERIFY_KEY = VerifyKey(SWIFTAPI_PUBLIC_KEY)
+
+
+def verify_signature(attestation: Dict[str, Any], ignore_expiry: bool = False) -> bool:
+    """
+    Verify the Ed25519 signature of an execution attestation.
+
+    This is OFFLINE verification - no network required.
+    The signature proves the attestation was issued by SwiftAPI.
+
+    Signature authenticity is permanent. Expiry is about the execution window,
+    not whether the attestation is genuine. Use ignore_expiry=True for audit
+    and post-hoc verification.
+
+    Args:
+        attestation: The execution_attestation dict from /verify response
+        ignore_expiry: If True, verify signature without checking expiry
+
+    Returns:
+        True if signature is valid
+
+    Raises:
+        SignatureVerificationError: If signature is invalid or missing
+        AttestationExpiredError: If attestation has expired (and ignore_expiry is False)
+    """
+    if not isinstance(attestation, dict):
+        raise SignatureVerificationError("Attestation must be a JSON object")
+
+    # Extract required fields
+    signature_b64 = attestation.get("signature")
+    if not signature_b64:
+        raise SignatureVerificationError("Missing signature in attestation")
+
+    jti = attestation.get("jti")
+    action_fingerprint = attestation.get("action_fingerprint")
+    expires_at = attestation.get("expires_at")
+
+    if not all(isinstance(value, str) and value for value in (jti, action_fingerprint, expires_at)):
+        raise SignatureVerificationError("Incomplete attestation: missing required fields")
+
+    # Verify signature FIRST — authenticity is permanent
+    try:
+        signed_payload = _reconstruct_signed_payload(attestation)
+    except (TypeError, ValueError):
+        raise SignatureVerificationError("Attestation contains invalid JSON fields")
+
+    try:
+        signature = base64.b64decode(signature_b64, validate=True)
+    except Exception as e:
+        raise SignatureVerificationError(f"Invalid signature encoding: {e}")
+
+    try:
+        VERIFY_KEY.verify(signed_payload, signature)
+    except (BadSignatureError, ValueError, TypeError):
+        raise SignatureVerificationError(
+            "INVALID SIGNATURE: Attestation was not signed by SwiftAPI. "
+            "This could indicate a forged or tampered attestation."
+        )
+
+    # Check expiration AFTER signature (execution window, not authenticity)
+    if not ignore_expiry:
+        try:
+            expiry = datetime.fromisoformat(expires_at.replace("Z", "+00:00"))
+            if expiry.tzinfo is None:
+                raise ValueError("Expiration must include a timezone")
+            now = datetime.now(timezone.utc)
+            if now >= expiry:
+                raise AttestationExpiredError(f"Attestation expired at {expires_at}")
+        except ValueError as e:
+            raise SignatureVerificationError(f"Invalid expiration format: {e}")
+
+    return True
+
+
+def _reconstruct_signed_payload(attestation: Dict[str, Any]) -> bytes:
+    """
+    Reconstruct the exact payload that was signed by SwiftAPI.
+
+    The server signs the attestation BEFORE adding signature/signing_mode fields.
+    We must reconstruct that exact payload.
+    """
+    # Copy attestation and remove fields that weren't in the signed payload.
+    # signature/signing_mode are added after signing.
+    # /attest appends action_data and policy diagnostics after signing.
+    # They are never used as authorization evidence.
+    _unsigned = (
+        "signature", "signing_mode", "action_data", "denial_reason",
+        "violated_policies", "evaluated_policies", "evaluation_context",
+    )
+    signed_fields = {k: v for k, v in attestation.items() if k not in _unsigned}
+
+    # Deterministic JSON serialization (must match server exactly)
+    payload_str = json.dumps(signed_fields, sort_keys=True, separators=(",", ":"))
+    return payload_str.encode("utf-8")
+
+
+def _snapshot_action_data(data: Dict[str, Any]) -> Dict[str, Any]:
+    """Detach request data and normalize it exactly as JSON transport does."""
+    try:
+        return json.loads(json.dumps(data, allow_nan=False))
+    except (TypeError, ValueError):
+        raise SwiftAPIError("Action data must contain JSON-serializable values")
+
+
+def _action_fingerprint(data: Dict[str, Any], truncated: bool = False) -> str:
+    """Match the backend's canonical JSON hash (/attest uses 32 hex chars)."""
+    canonical = json.dumps(data, sort_keys=True, separators=(",", ":"))
+    fingerprint = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+    return fingerprint[:32] if truncated else fingerprint
+
+
+def _validate_action_binding(
+    attestation: Dict[str, Any], action_type: str, action_fingerprint: str
+) -> bool:
+    """Check signed execution fields after verify_signature has succeeded."""
+    if attestation.get("action_type") != action_type:
+        raise SignatureVerificationError("Attestation action type does not match the request")
+    if attestation.get("action_fingerprint") != action_fingerprint:
+        raise SignatureVerificationError("Attestation action fingerprint does not match the request")
+    approved = attestation.get("approved")
+    if type(approved) is not bool:
+        raise SignatureVerificationError("Attestation approval must be a boolean")
+    return approved
+
+
+def get_public_key() -> str:
+    """Return SwiftAPI's public key in Base64 format."""
+    return SWIFTAPI_PUBLIC_KEY_B64
+
+
+def is_valid(attestation: Dict[str, Any], ignore_expiry: bool = False) -> bool:
+    """
+    Check if attestation is valid without raising exceptions.
+
+    Args:
+        attestation: The execution_attestation dict
+        ignore_expiry: If True, only check signature authenticity
+
+    Returns:
+        True if valid, False otherwise
+    """
+    try:
+        return verify_signature(attestation, ignore_expiry=ignore_expiry)
+    except Exception:
+        return False
+
+
+def claim_attestation(attestation: Dict[str, Any]) -> None:
+    """One-use local replay claim; call only after signature and action verification."""
+    import os
+    from pathlib import Path
+    from .brake.core import ReplayLedger
+    root = Path(os.environ.get("SWIFTAPI_HOME", Path.home() / ".local/share/swiftapi"))
+    ReplayLedger(root).claim(SWIFTAPI_PUBLIC_KEY_B64, attestation["jti"])

swiftapi_python-1.3.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: swiftapi-python
+Version: 1.3.0
+Summary: SwiftAPI Python SDK - AI Action Verification Gateway
+Author-email: Rayan Pal <rayan@swiftapi.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://swiftapi.ai
+Project-URL: Documentation, https://getswiftapi.com/docs
+Keywords: swiftapi,ai,verification,attestation,security,governance,enforcement
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.32.3
+Requires-Dist: pynacl<2,>=1.5.0
+Requires-Dist: colorama<1,>=0.4.6
+Requires-Dist: tomli<3,>=2; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: hypothesis<7,>=6; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: types-requests<3,>=2.32.3; extra == "dev"
+Dynamic: license-file
+
+# SwiftAPI Python SDK
+
+A prerequisite before a protected action. Local Swift Brake verifies explicit
+permission, executes its registered capability once, and creates signed receipts.
+Codex or Claude Code remains the coding agent. No second model is involved.
+
+```bash
+pip install swiftapi-python
+swiftapi doctor
+swiftapi brake test
+swiftapi brake install --dry-run
+swiftapi brake install
+```
+
+Python 3.9+, macOS and Linux. The local test needs no account, API key, model,
+or cloud service. Restart the coding agent after installing the MCP integration.
+
+## Try the brake
+
+```bash
+swiftapi brake propose hello.txt "Hello from Swift Brake"
+# Copy the returned request_id into the following commands.
+swiftapi brake execute REQUEST_ID
+# GATE_BLOCK: no marker is written.
+swiftapi brake authorize REQUEST_ID
+swiftapi brake execute REQUEST_ID
+# AUTHORIZED_EXECUTION: exact marker bytes are written once.
+swiftapi brake execute REQUEST_ID
+# GATE_BLOCK: the authorization cannot execute again.
+swiftapi status
+swiftapi receipts
+swiftapi verify RECEIPT_PATH --public-key PUBLIC_KEY_PATH
+```
+
+`status` prints the sandbox and public-key path. `execute` returns the receipt
+path. The operator authorizes in a separate terminal; authorization is deliberately
+absent from the MCP tool surface. A signature requires an independently trusted
+verification key, never a key blindly accepted from the receipt itself.
+
+`swiftapi brake` presents `swiftapi>` and delegates ordinary input to the existing
+Codex CLI. `swiftapi brake --agent claude` uses Claude Code. These host calls use
+your existing account; the local test itself makes no model calls.
+
+## Python
+
+The old imports remain available: `from swiftapi import SwiftAPI, Enforcement`.
+The new local API does not require a remote account:
+
+```python
+from pathlib import Path
+from tempfile import mkdtemp
+from swiftapi import ActionEnvelope, BindingCondition, LocalAuthority, LocalGuard
+
+action = ActionEnvelope("example.append", {"value": "verified"}, "Append one value")
+state = {"operator_approved": True}  # Supplied by trusted application code.
+condition = BindingCondition(action.action_hash, state)
+guard = LocalGuard(LocalAuthority(), Path(mkdtemp()) / "ledger")
+values = []
+guard.run(
+    lambda: values.append("verified"),
+    action=action.capability, params=action.params, intent=action.intent,
+    condition=condition, state=state,
+)
+assert values == ["verified"]
+```
+
+A callback's code must actually implement its supplied action description.
+For an untrusted agent, use a registered broker operation that constructs and
+executes the same canonical parameters. The bundled MCP operation creates a new
+small UTF-8 marker in its own sandbox; it cannot run a shell or overwrite files.
+
+## What is enforced
+
+An authorization binds an action hash, capability, condition hash, state hash,
+nonce, issue time, and expiry. Ed25519 verification and a durable SQLite replay
+claim happen before execution. Execution is never retried. Missing, malformed,
+forged, expired, replayed, or mismatched authorization fails closed.
+
+This guarantee applies to mediated capabilities. Arbitrary host tools are outside
+the broker. Local same-user key storage supports development and CI; a malicious
+process able to read the signer, change the gate, or mutate the ledger can bypass
+that trust boundary. Production credentials and signing authority require process
+or account isolation from untrusted agent code. Instructions and hooks are not a
+universal security boundary.
+
+## Research is measured separately
+
+`GATE_BLOCK` is deterministic enforcement, not native EOS. Successful empty
+provider output is classified as a black-box `PROVIDER_VOID` with V0/V1/V2/VU
+subtypes. Only exposed native token evidence can qualify as `NATIVE_VOID`.
+The package does not download or retrain research models. The frozen
+[PCCG-2 release](https://getswiftapi.com/pccg-2) and
+[research library](https://getswiftapi.com/research) preserve the empirical,
+causal, theoretical, and protocol boundaries.
+
+## Documentation
+
+Start with [Quickstart](docs/QUICKSTART.md). See [concepts](docs/CONCEPTS.md),
+[local brake](docs/LOCAL_BRAKE.md), [Codex](docs/CODEX.md),
+[Claude Code](docs/CLAUDE_CODE.md), [Python SDK](docs/PYTHON_SDK.md),
+[conditions](docs/CONDITIONS.md), [action envelopes](docs/ACTION_ENVELOPES.md),
+[receipts](docs/RECEIPTS.md), [verification](docs/VERIFICATION.md),
+[remote authority](docs/REMOTE_SWIFTAPI.md), [BYOK](docs/BYOK.md),
+[security](docs/SECURITY_MODEL.md), [threat model](docs/THREAT_MODEL.md),
+[native noncontinuation](docs/NATIVE_NONCONTINUATION.md),
+[benchmarking](docs/BENCHMARKING.md), and [provenance](docs/RESEARCH_PROVENANCE.md).
+
+[Migration from 1.2.2](MIGRATION_1_2_2.md) documents security corrections and
+termination-metadata changes. Historical 1.2.2 bytes remain immutable on PyPI.
+
+MIT license. Research and software by Rayan Pal / SwiftAPI Labs.

swiftapi_python-1.3.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+swiftapi/__init__.py,sha256=oJ91q9TbmnCdPYUuKXPWtW3ne6aQBEo40qANvSWmI_k,1867
+swiftapi/__main__.py,sha256=ee5vE0xcUZM3fPmxicvcw-IJXkm6nOwxARREHBWpF8Q,47
+swiftapi/anthropic.py,sha256=f8lB4XRI4VmCqOLiQaDX5aFNZNzPiR6jheuv40f0umk,8209
+swiftapi/cli.py,sha256=hP9wcYQGQOpwe8LNjdiNQ2GETInRzHumPe5xGhQnCpo,5860
+swiftapi/client.py,sha256=jvAGLGeD-8evyWEWsRGKJZgb_PtQdNgztJR4OQgD48c,11094
+swiftapi/enforcement.py,sha256=EzhR9TVbXe-NqAXxrIfJpg1hSK0gmB9rK--rt2AuL_s,8659
+swiftapi/exceptions.py,sha256=hBleOCc1WwDEM70WNYTy1TDOSOaBJSx3PtzFzfmVOGY,1701
+swiftapi/openai.py,sha256=3eI1T-hF20Apymp6Vkh9jskALmFmQCtzptH4jh9B544,8432
+swiftapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+swiftapi/utils.py,sha256=Sn6ED6ltECCYc-ce9fhxZxgzBthvflPCZelXPPzskZM,3145
+swiftapi/verifier.py,sha256=JkFM9wUFVqy_M98jm4PLWUBtZFTXsItPSGGyZpiqoo0,7058
+swiftapi/brake/__init__.py,sha256=OGhusWHNo8aK1HSsJT6yjEBLpRrQtBJscuRFEj6hv7U,883
+swiftapi/brake/benchmarks.py,sha256=gqURdxdu1FMKCzw8i3c8zXewBzHGdNsMQjiu0DvnFbo,4469
+swiftapi/brake/broker.py,sha256=J5dq9hW1hcBAZ6X1bDkiOr_4R2qZfxQgmTATlwidVF4,10775
+swiftapi/brake/core.py,sha256=_Jd1O-10CVb9-1DzgqCQ3o0D1mvM5SCMlsf6q-bbP6E,14244
+swiftapi/brake/install.py,sha256=VZKGF0r6FfY0CKJ6c_-g_xlGW3TFI4kLooUJq9FYcRM,11137
+swiftapi/brake/mcp.py,sha256=y6VGP37U8IXRYO_bptwo9JOrE6QXkp8Qmojoo32QN6g,5695
+swiftapi/brake/observations.py,sha256=RBkkmzBEzJwq-JG9yYZR9VtsMNocRoOgxCw6iHohG_E,1963
+swiftapi/brake/qualification.py,sha256=tRkx67lKH8c018atUmllWajZwMUccpNf1QptJQIU6ik,4031
+swiftapi/brake/remote.py,sha256=qPj1t0b7uQsQWdTz_3NZz1roxjXH6Mu9ORxVK8amm-4,3150
+swiftapi_python-1.3.0.dist-info/licenses/LICENSE,sha256=btq3h42ZP3swvtQ3ak5k3sP_Y6yRwzL5zrV7EzNeRus,1087
+swiftapi_python-1.3.0.dist-info/METADATA,sha256=FRDqYXMzo9uf9PzJjT9XmyCm64fwc988J-liY3j1qJM,6357
+swiftapi_python-1.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+swiftapi_python-1.3.0.dist-info/entry_points.txt,sha256=rIhaU6i_Q2sPz0b8a7Hpe7crjULOwJfxdL1-AIcKRAw,47
+swiftapi_python-1.3.0.dist-info/top_level.txt,sha256=oio-d2BTrT91P7dmufUhlSYjOtWBh4bOYz6rsTDDvu4,9
+swiftapi_python-1.3.0.dist-info/RECORD,,

{swiftapi_python-1.2.1.dist-info → swiftapi_python-1.3.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.0)
+Generator: setuptools (84.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

swiftapi_python-1.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+swiftapi = swiftapi.cli:main