secure-ai-guard 0.2.0__tar.gz

secure_ai_guard-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+.venv/
+build/

secure_ai_guard-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Secure AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

secure_ai_guard-0.2.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: secure-ai-guard
+Version: 0.2.0
+Summary: Data loss prevention for AI agents. Inspect what an agent is about to do, before it does it.
+Project-URL: Homepage, https://secureai.one/developers
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,audit,dlp,mcp,redaction,security
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# secure-ai
+
+Data loss prevention for AI agents. Put a check in front of every action an
+agent takes, before it takes it.
+
+```bash
+pip install secure-ai-guard
+```
+
+> **Status:** written, not yet executed — there was no Python interpreter on
+> the machine this was built on. Run `pytest` before trusting it. The
+> TypeScript SDK it mirrors does pass its suite.
+
+## The one thing worth knowing
+
+`guard` wraps a function your agent already calls, and calls it with the
+**rewritten** arguments:
+
+```python
+from secure_ai import SecureAI
+
+sai = SecureAI(api_key=os.environ["SECURE_AI_KEY"], agent="support-bot")
+
+send_email = sai.guard("email.send", mailer.send)
+send_email({"to": "ana@clientfirm.com", "body": "About invoice 4471…"})
+```
+
+The agent wrote a real address. `mailer.send` receives a stand-in. Nothing in
+the agent's code had to check a decision — which is the point. Protection that
+depends on remembering to check it ends at the fourteenth call site.
+
+If the policy refuses, the wrapped function is never called and `ActionBlocked`
+is raised.
+
+As a decorator:
+
+```python
+@sai.guarded("email.send")
+def send(payload): ...
+```
+
+## A whole toolbelt at once
+
+```python
+tools = sai.guard_tools(agent.tools)
+```
+
+Wraps whichever attribute holds the callable — `func`, `_run`, `run` — so
+LangChain and similar frameworks are governed in one line. Shapes it does not
+recognise are returned untouched rather than raising.
+
+## Rules
+
+Rules live on the account, not in the request. An agent cannot argue with them.
+
+```python
+sai.set_policy({
+    "fallback": "redact",
+    "rules": [
+        {"kind": "secret", "decision": "block"},
+        {"kind": "card", "decision": "block", "direction": "outbound"},
+        {"kind": "email", "decision": "allow", "tools": ["crm.*"]},
+    ],
+    "denyTools": ["shell.*"],
+})
+
+sai.allow_value("@ourcompany.com")   # stop flagging your own domain
+```
+
+When an action contains several findings, the **most severe** decision wins.
+
+## The trail
+
+```python
+sai.summary()                # counts over a recent window
+sai.audit(limit=100)         # the records themselves
+```
+
+Records hold the **kind and location** of what was found — `card` at
+`body.payment.number` — and never the value. `Finding` has no field for one.
+
+## When Secure AI is unreachable
+
+Default is `on_unreachable="closed"`: the action does not happen. Correct for a
+security control, and it does mean an outage here stops agents.
+
+```python
+SecureAI(api_key=..., on_unreachable="open")   # availability over control
+```
+
+Failing open never waves a real refusal through — a 401, 402 or quota error is
+an answer, not an outage, and still raises.
+
+## No dependencies
+
+Standard library only. This runs beside your model client and your framework,
+and every dependency it adds is a version conflict it can cause.
+
+Full reference: <https://secureai.one/developers>

secure_ai_guard-0.2.0/README.md

@@ -0,0 +1,99 @@
+# secure-ai
+
+Data loss prevention for AI agents. Put a check in front of every action an
+agent takes, before it takes it.
+
+```bash
+pip install secure-ai-guard
+```
+
+> **Status:** written, not yet executed — there was no Python interpreter on
+> the machine this was built on. Run `pytest` before trusting it. The
+> TypeScript SDK it mirrors does pass its suite.
+
+## The one thing worth knowing
+
+`guard` wraps a function your agent already calls, and calls it with the
+**rewritten** arguments:
+
+```python
+from secure_ai import SecureAI
+
+sai = SecureAI(api_key=os.environ["SECURE_AI_KEY"], agent="support-bot")
+
+send_email = sai.guard("email.send", mailer.send)
+send_email({"to": "ana@clientfirm.com", "body": "About invoice 4471…"})
+```
+
+The agent wrote a real address. `mailer.send` receives a stand-in. Nothing in
+the agent's code had to check a decision — which is the point. Protection that
+depends on remembering to check it ends at the fourteenth call site.
+
+If the policy refuses, the wrapped function is never called and `ActionBlocked`
+is raised.
+
+As a decorator:
+
+```python
+@sai.guarded("email.send")
+def send(payload): ...
+```
+
+## A whole toolbelt at once
+
+```python
+tools = sai.guard_tools(agent.tools)
+```
+
+Wraps whichever attribute holds the callable — `func`, `_run`, `run` — so
+LangChain and similar frameworks are governed in one line. Shapes it does not
+recognise are returned untouched rather than raising.
+
+## Rules
+
+Rules live on the account, not in the request. An agent cannot argue with them.
+
+```python
+sai.set_policy({
+    "fallback": "redact",
+    "rules": [
+        {"kind": "secret", "decision": "block"},
+        {"kind": "card", "decision": "block", "direction": "outbound"},
+        {"kind": "email", "decision": "allow", "tools": ["crm.*"]},
+    ],
+    "denyTools": ["shell.*"],
+})
+
+sai.allow_value("@ourcompany.com")   # stop flagging your own domain
+```
+
+When an action contains several findings, the **most severe** decision wins.
+
+## The trail
+
+```python
+sai.summary()                # counts over a recent window
+sai.audit(limit=100)         # the records themselves
+```
+
+Records hold the **kind and location** of what was found — `card` at
+`body.payment.number` — and never the value. `Finding` has no field for one.
+
+## When Secure AI is unreachable
+
+Default is `on_unreachable="closed"`: the action does not happen. Correct for a
+security control, and it does mean an outage here stops agents.
+
+```python
+SecureAI(api_key=..., on_unreachable="open")   # availability over control
+```
+
+Failing open never waves a real refusal through — a 401, 402 or quota error is
+an answer, not an outage, and still raises.
+
+## No dependencies
+
+Standard library only. This runs beside your model client and your framework,
+and every dependency it adds is a version conflict it can cause.
+
+Full reference: <https://secureai.one/developers>

secure_ai_guard-0.2.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "secure-ai-guard"
+version = "0.2.0"
+description = "Data loss prevention for AI agents. Inspect what an agent is about to do, before it does it."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["dlp", "ai-agents", "security", "redaction", "audit", "mcp"]
+# No dependencies, deliberately. This runs inside somebody's agent beside
+# their model client and framework; every dependency it adds is a version
+# conflict it can cause in a process already carrying too many.
+dependencies = []
+
+[project.urls]
+Homepage = "https://secureai.one/developers"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["secure_ai"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

secure_ai_guard-0.2.0/secure_ai/__init__.py

@@ -0,0 +1,512 @@
+"""Secure AI — data loss prevention for AI agents.
+
+The API is plain HTTP and anybody can call it with ``requests``. This exists
+because the shape that makes the product work is not "call an endpoint", it is
+"put a check in front of every action", and the difference between those two is
+whether somebody remembers to do it at the fourteenth call site.
+
+So the centre of this package is :meth:`SecureAI.guard`, which wraps a function
+an agent already calls and invokes it with the *rewritten* arguments::
+
+    send = sai.guard("email.send", raw_send)
+    send({"to": "ana@clientfirm.com"})   # raw_send receives a stand-in
+
+Python before TypeScript would have been the better order — LangChain, CrewAI,
+LlamaIndex and most agent code is Python — and this is the correction.
+
+Why no dependencies
+-------------------
+
+This runs inside somebody's agent, beside their model client, their framework
+and their vendor SDKs. Every dependency it adds is a version conflict it can
+cause in a process already carrying too many, and a security tool that is
+awkward to install is one that gets removed. So: ``urllib`` from the standard
+library, nothing else. It is slower per call than ``httpx`` and that is not the
+constraint — the constraint is that ``pip install secure-ai`` never fails.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field, replace
+from typing import Any, Callable, Iterable, Literal, TypeVar
+from urllib.parse import quote, urlencode
+
+__all__ = [
+    "SecureAI",
+    "ActionBlocked",
+    "ApprovalRefused",
+    "SecureAIError",
+    "Approval",
+    "Finding",
+    "Inspection",
+    "KINDS",
+]
+
+__version__ = "0.2.0"
+
+Decision = Literal["allow", "redact", "approve", "block"]
+Direction = Literal["outbound", "inbound"]
+ApprovalStatus = Literal["pending", "approved", "denied", "expired"]
+
+#: Every kind the scanner reports, in the order a policy editor should list
+#: them: the ones that end careers first. Mirrors KINDS in the Worker.
+KINDS = (
+    "secret", "card", "iban", "ssn", "govid",
+    "email", "phone", "address", "postcode", "name", "host",
+)
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class Finding:
+    """Something the scanner located: what it was and where it sat.
+
+    Deliberately no ``value``. The trail never carries one and neither does
+    this, so a caller logging a finding cannot accidentally log the thing the
+    product exists to protect.
+    """
+
+    kind: str
+    path: str
+    decision: Decision
+
+
+@dataclass(frozen=True)
+class Inspection:
+    decision: Decision
+    #: The action, ready to send. ``None`` when blocked — a refusal carries
+    #: nothing sendable, so a caller cannot reach past the decision.
+    input: Any
+    #: ``{stand_in: real}``. Keep it: it is the only way back, and it is not
+    #: stored on our side.
+    map: dict[str, str]
+    findings: list[Finding]
+    tool_denied: bool
+    policy_source: str
+    audit_id: str
+    #: Set when the decision is "approve": the id to come back with once a
+    #: person has decided.
+    approval_id: str | None = None
+    #: When waiting stops being worth it. Milliseconds since epoch.
+    expires_at: int | None = None
+
+
+def _sendable(tool: str, verdict: "Inspection", original: Any) -> Any:
+    """What to hand the wrapped function.
+
+    The API omits ``input`` only on a block, so on any other decision it is
+    there. The question is what to do if it is not, and the answer is not
+    "send what the caller had".
+
+    On a redact the caller's input is the one thing that must not go: it still
+    holds the values the decision just said to replace. Falling back to it
+    turns a missing field into the library doing the exact opposite of its
+    purpose, silently, with the trail recording a redaction that did not
+    happen.
+
+    On an allow nothing was rewritten, so the caller's own input is the right
+    thing to pass and the fallback belongs there.
+    """
+    if verdict.input is not None:
+        return verdict.input
+    if verdict.decision == "redact":
+        raise SecureAIError(
+            f"Secure AI decided to redact {tool} but returned nothing to send. "
+            "The original was not sent: it still holds the values that decision was about.",
+            502,
+            "missing_rewritten_input",
+        )
+    return original
+
+
+def _approval(raw: dict[str, Any]) -> "Approval":
+    return Approval(
+        id=raw.get("id", ""),
+        created_at=int(raw.get("createdAt", 0)),
+        expires_at=int(raw.get("expiresAt", 0)),
+        status=raw.get("status", "pending"),
+        agent=raw.get("agent"),
+        tool=raw.get("tool", ""),
+        key_id=raw.get("keyId", ""),
+        findings=[Finding(f["kind"], f["path"], f["decision"]) for f in raw.get("findings", [])],
+        decided_by=raw.get("decidedBy"),
+        decided_at=raw.get("decidedAt"),
+        note=raw.get("note"),
+    )
+
+
+@dataclass(frozen=True)
+class Approval:
+    """An action a rule stopped and handed to a person.
+
+    Holds the shape of what the agent wanted to do — the tool and the kinds it
+    carried — and never the payload, for the same reason the trail does not.
+    """
+
+    id: str
+    created_at: int
+    expires_at: int
+    status: ApprovalStatus
+    agent: str | None
+    tool: str
+    key_id: str
+    findings: list[Finding]
+    decided_by: str | None = None
+    decided_at: int | None = None
+    note: str | None = None
+
+
+class SecureAIError(RuntimeError):
+    """The API answered, and said no.
+
+    Distinct from :class:`ActionBlocked`: this is a problem with the call — no
+    key, no subscription, over quota — not a decision about the action.
+    """
+
+    def __init__(self, message: str, status: int, code: str | None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class ActionBlocked(Exception):
+    """The policy refused this action.
+
+    Raised rather than returned so a caller cannot ignore it by not reading a
+    field. A guarded function that returned a verdict would be protection you
+    have to remember to check.
+    """
+
+    def __init__(self, tool: str, result: Inspection) -> None:
+        if result.tool_denied:
+            what = "the tool itself is not permitted"
+        else:
+            blocked = [f for f in result.findings if f.decision == "block"]
+            what = ", ".join(f"{f.kind} at {f.path or 'the input'}" for f in blocked) or "policy"
+        super().__init__(f"Secure AI refused {tool}: {what}.")
+        self.tool = tool
+        self.findings = result.findings
+        self.tool_denied = result.tool_denied
+        self.audit_id = result.audit_id
+
+
+class ApprovalRefused(Exception):
+    """A person was asked, and the action did not go.
+
+    Three ways to arrive here and they are not the same: denied means somebody
+    looked and said no; expired means nobody looked in time, which is also a
+    no because an approval that runs out is a refusal rather than a release;
+    pending means the caller asked not to wait.
+    """
+
+    def __init__(
+        self,
+        tool: str,
+        approval_id: str,
+        status: ApprovalStatus,
+        note: str | None = None,
+    ) -> None:
+        if status == "pending":
+            what = "and it is still waiting for a person"
+        elif status == "expired":
+            what = "and nobody answered before it expired"
+        else:
+            what = "and it was refused" + (": " + note if note else "")
+        super().__init__(f"Secure AI held {tool} for approval {what}.")
+        self.tool = tool
+        self.approval_id = approval_id
+        self.status = status
+        self.note = note
+
+
+@dataclass
+class SecureAI:
+    """A client.
+
+    :param api_key: from Settings → Developer.
+    :param agent: names this agent in the trail so its actions group together.
+        Worth setting — a trail where everything is unnamed is a trail nobody
+        can ask a question of.
+    :param on_unreachable: what to do when Secure AI itself cannot be reached.
+        ``"closed"`` (the default) raises, so an action is not taken while the
+        thing governing it is down. That is correct for a security control and
+        it does mean an outage here stops agents. ``"open"`` lets the action
+        through unchecked; it exists because some workloads genuinely prefer
+        availability, and because somebody who wants it will otherwise write a
+        ``try/except`` that also swallows real refusals.
+    """
+
+    api_key: str
+    base_url: str = "https://api.secureai.one"
+    agent: str | None = None
+    timeout: float = 5.0
+    on_unreachable: Literal["closed", "open"] = "closed"
+    _opener: Any = field(default=None, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        if not self.api_key:
+            raise ValueError("SecureAI needs an api_key.")
+        self.base_url = self.base_url.rstrip("/")
+
+    # ── plumbing ────────────────────────────────────────────────────────────
+
+    def _request(self, method: str, path: str, body: Any = None) -> Any:
+        data = None if body is None else json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(
+            f"{self.base_url}{path}",
+            data=data,
+            method=method,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                **({"Content-Type": "application/json"} if data is not None else {}),
+            },
+        )
+        opener = self._opener or urllib.request.urlopen
+        try:
+            with opener(req, timeout=self.timeout) as res:  # type: ignore[operator]
+                raw = res.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            raw = exc.read().decode("utf-8", errors="replace")
+            message, code = f"Secure AI returned {exc.code}.", None
+            try:
+                err = (json.loads(raw) or {}).get("error") or {}
+                message = err.get("message") or message
+                code = err.get("code")
+            except json.JSONDecodeError:
+                # Something in front of the API answered, not the API.
+                pass
+            raise SecureAIError(message, exc.code, code) from None
+        return json.loads(raw) if raw else None
+
+    # ── the API ─────────────────────────────────────────────────────────────
+
+    def inspect(
+        self,
+        tool: str,
+        action_input: Any,
+        *,
+        direction: Direction = "outbound",
+        agent: str | None = None,
+        approval_id: str | None = None,
+    ) -> Inspection:
+        """Judge an action without taking it.
+
+        Pass ``approval_id`` to come back with a yes a person has given.
+        The server re-checks the shape of what is being sent against what was
+        approved, so one yes cannot be spent on a different action.
+        """
+        payload: dict[str, Any] = {
+            "tool": tool,
+            "input": action_input,
+            "direction": direction,
+            "agent": agent or self.agent,
+        }
+        if approval_id:
+            payload["approvalId"] = approval_id
+        body = self._request("POST", "/v1/inspect", payload)
+        return Inspection(
+            decision=body["decision"],
+            input=body.get("input"),
+            map=body.get("map") or {},
+            findings=[Finding(f["kind"], f["path"], f["decision"]) for f in body.get("findings", [])],
+            tool_denied=bool(body.get("toolDenied")),
+            policy_source=body.get("policySource", "default"),
+            audit_id=body.get("auditId", ""),
+            approval_id=body.get("approvalId"),
+            expires_at=body.get("expiresAt"),
+        )
+
+    def get_policy(self) -> dict[str, Any]:
+        """The rules in force."""
+        return self._request("GET", "/v1/policy")
+
+    def set_policy(self, policy: dict[str, Any]) -> dict[str, Any]:
+        """Replace them. Refused whole if any rule is malformed, naming it."""
+        return self._request("PUT", "/v1/policy", {"policy": policy})
+
+    def allow_value(self, value: str) -> dict[str, Any]:
+        """Stop flagging a value — your own domain, a shared mailbox.
+
+        Applies to every agent on the account from the next action onward. A
+        leading ``@`` exempts a whole domain.
+        """
+        return self._request("POST", "/v1/policy/allow", {"value": value})
+
+    def audit(self, *, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]:
+        """What agents did, newest first. Kinds and locations, never values."""
+        query = []
+        if limit:
+            query.append(f"limit={limit}")
+        if cursor:
+            query.append(f"cursor={urllib.parse.quote(cursor)}")
+        suffix = f"?{'&'.join(query)}" if query else ""
+        return self._request("GET", f"/v1/audit{suffix}")
+
+    def summary(self, *, limit: int | None = None) -> dict[str, Any]:
+        """The counts, over a recent window."""
+        suffix = f"?limit={limit}" if limit else ""
+        return self._request("GET", f"/v1/audit/summary{suffix}")
+
+    def restore(self, text: str, mapping: dict[str, str]) -> str:
+        """Put real values back into a reply, using an inspection's map."""
+        return self._request("POST", "/v1/restore", {"text": text, "map": mapping})["text"]
+
+    # ── the point of the library ────────────────────────────────────────────
+
+    def approval(self, approval_id: str) -> Approval:
+        """Read one back."""
+        body = self._request("GET", f"/v1/approvals/{quote(approval_id, safe='')}")
+        return _approval(body["approval"])
+
+    def approvals(
+        self,
+        *,
+        status: ApprovalStatus | None = None,
+        limit: int | None = None,
+    ) -> list[Approval]:
+        """The queue, newest first."""
+        query: dict[str, Any] = {}
+        if status:
+            query["status"] = status
+        if limit:
+            query["limit"] = limit
+        path = "/v1/approvals" + ("?" + urlencode(query) if query else "")
+        return [_approval(a) for a in self._request("GET", path).get("approvals", [])]
+
+    def wait_for_approval(self, approval_id: str, *, poll_seconds: float = 2.0) -> Approval:
+        """Block until somebody decides, or until the window closes.
+
+        Stops at the approval's own expiry rather than running forever: the
+        server denies it at that point regardless, so a caller polling past it
+        is waiting for an answer that has already been given.
+        """
+        while True:
+            current = self.approval(approval_id)
+            if current.status != "pending":
+                return current
+            if time.time() * 1000 >= current.expires_at:
+                return replace(current, status="expired")
+            time.sleep(poll_seconds)
+
+    def guard(
+        self,
+        tool: str,
+        fn: Callable[[Any], T],
+        *,
+        direction: Direction = "outbound",
+        agent: str | None = None,
+        wait_for_approval: bool = True,
+        poll_seconds: float = 2.0,
+    ) -> Callable[[Any], T]:
+        """Wrap a function so it cannot run unchecked.
+
+        The returned callable inspects, then calls ``fn`` with the **rewritten**
+        arguments — so an agent that never looks at a decision still cannot send
+        a real card number — and raises :class:`ActionBlocked` when the policy
+        refuses.
+
+        Calling ``fn`` with the redacted input rather than the caller's is the
+        whole mechanism. Returning a verdict for the caller to check would make
+        protection opt-in at every site, which is what this exists to stop.
+
+        An action held for a person waits by default. Pass
+        ``wait_for_approval=False`` to get :class:`ApprovalRefused` straight
+        away and do the waiting yourself.
+        """
+
+        def guarded(action_input: Any) -> T:
+            try:
+                verdict = self.inspect(tool, action_input, direction=direction, agent=agent)
+            except SecureAIError:
+                # A refusal by the API is a real answer and must not be
+                # mistaken for an outage, whatever on_unreachable says.
+                raise
+            except Exception:
+                if self.on_unreachable == "open":
+                    return fn(action_input)
+                raise
+
+            if verdict.decision == "block":
+                raise ActionBlocked(tool, verdict)
+
+            # Held for a person.
+            #
+            # This branch did not exist. "approve" did not match "block", so
+            # the action was sent immediately: on Python a policy saying an
+            # action must wait for a human was not weakened but bypassed, and
+            # the agent was told the check had passed.
+            if verdict.decision == "approve":
+                approval_id = verdict.approval_id or ""
+                if not approval_id:
+                    raise ActionBlocked(tool, verdict)
+                if not wait_for_approval:
+                    raise ApprovalRefused(tool, approval_id, "pending")
+                decided = self.wait_for_approval(approval_id, poll_seconds=poll_seconds)
+                if decided.status != "approved":
+                    raise ApprovalRefused(tool, approval_id, decided.status, decided.note)
+                # Back with the id. The server re-checks the shape of what is
+                # being sent, so a yes cannot be spent on a different action.
+                after = self.inspect(
+                    tool,
+                    action_input,
+                    direction=direction,
+                    agent=agent,
+                    approval_id=approval_id,
+                )
+                if after.decision == "block":
+                    raise ActionBlocked(tool, after)
+                return fn(_sendable(tool, after, action_input))
+
+            return fn(_sendable(tool, verdict, action_input))
+
+        guarded.__name__ = getattr(fn, "__name__", "guarded")
+        guarded.__doc__ = getattr(fn, "__doc__", None)
+        return guarded
+
+    def guarded(self, tool: str, **kwargs: Any) -> Callable[[Callable[[Any], T]], Callable[[Any], T]]:
+        """:meth:`guard` as a decorator.
+
+        ::
+
+            @sai.guarded("email.send")
+            def send(payload): ...
+        """
+
+        def decorate(fn: Callable[[Any], T]) -> Callable[[Any], T]:
+            return self.guard(tool, fn, **kwargs)
+
+        return decorate
+
+    def guard_tools(self, tools: Iterable[Any], *, name_attr: str = "name") -> list[Any]:
+        """Wrap a list of framework tool objects in place.
+
+        Agent frameworks hand around objects with a ``name`` and a callable —
+        LangChain's ``StructuredTool``, an OpenAI function spec, a plain
+        dataclass. This wraps whichever attribute holds the callable, so a
+        whole toolbelt is governed in one line rather than tool by tool.
+
+        Unknown shapes are returned untouched rather than raising: a helper
+        that refuses to start because one tool in a list is unfamiliar is a
+        helper nobody uses.
+        """
+        out = []
+        for tool in tools:
+            name = getattr(tool, name_attr, None) or getattr(tool, "__name__", None)
+            for attr in ("func", "_run", "run", "fn", "callable"):
+                target = getattr(tool, attr, None)
+                if callable(target) and name:
+                    try:
+                        setattr(tool, attr, self.guard(str(name), target))
+                    except (AttributeError, TypeError):
+                        # Frozen or slotted objects cannot be patched. Left
+                        # alone rather than failing the whole call.
+                        pass
+                    break
+            out.append(tool)
+        return out

secure_ai_guard-0.2.0/tests/test_secure_ai.py

@@ -0,0 +1,445 @@
+"""The Python SDK.
+
+NOT YET EXECUTED. There is no Python interpreter on the machine this was
+written on, so every test below is unrun. They are written to the same shape as
+the TypeScript suite — which does pass — and the behaviours they pin are the
+ones that suite already proves at the API boundary, so the risk is in this
+file's own syntax rather than in what it asserts. Run ``pytest`` once before
+trusting any of it, and treat a first-run failure as a bug in the SDK, not as
+a surprise.
+
+The behaviour worth most of these: ``guard`` calls the wrapped function with
+the *rewritten* input, not the caller's. That is what makes protection
+automatic rather than opt-in, and a refactor could quietly undo it — every test
+here would still pass if guard merely returned a verdict, unless one of them
+checks what the underlying function actually received.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import time
+import urllib.error
+
+import pytest
+
+from secure_ai import (
+    ActionBlocked,
+    ApprovalRefused,
+    Finding,
+    SecureAI,
+    SecureAIError,
+)
+
+
+class FakeResponse:
+    def __init__(self, body: object, status: int = 200) -> None:
+        self._raw = json.dumps(body).encode("utf-8")
+        self.status = status
+
+    def read(self) -> bytes:
+        return self._raw
+
+    def __enter__(self) -> "FakeResponse":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        return None
+
+
+def client(handler, **kwargs):
+    """A client whose opener records calls and returns what `handler` says."""
+    calls: list[dict] = []
+
+    def opener(req, timeout=None):  # noqa: ARG001 - signature matches urlopen
+        body = json.loads(req.data.decode("utf-8")) if req.data else None
+        calls.append({
+            "url": req.full_url,
+            "method": req.get_method(),
+            "body": body,
+            "headers": {k.lower(): v for k, v in req.headers.items()},
+        })
+        result = handler(req)
+        if isinstance(result, urllib.error.HTTPError):
+            raise result
+        return result
+
+    sai = SecureAI(api_key="sai_test", base_url="https://api.test", _opener=opener, **kwargs)
+    return calls, sai
+
+
+def http_error(status: int, body: object) -> urllib.error.HTTPError:
+    payload = json.dumps(body).encode("utf-8")
+    return urllib.error.HTTPError(
+        "https://api.test", status, "err", {}, io.BytesIO(payload)
+    )
+
+
+def allowed(value: object) -> FakeResponse:
+    return FakeResponse({
+        "decision": "allow", "input": value, "map": {}, "findings": [],
+        "toolDenied": False, "policySource": "default", "auditId": "a1",
+    })
+
+
+def redacted(value: object, mapping: dict) -> FakeResponse:
+    return FakeResponse({
+        "decision": "redact", "input": value, "map": mapping, "findings": [],
+        "toolDenied": False, "policySource": "account", "auditId": "a2",
+    })
+
+
+def blocked(findings: list | None = None, tool_denied: bool = False) -> FakeResponse:
+    return FakeResponse({
+        "decision": "block", "map": {},
+        "findings": findings if findings is not None else
+            [{"kind": "secret", "path": "headers.authorization", "decision": "block"}],
+        "toolDenied": tool_denied, "policySource": "account", "auditId": "a3",
+    })
+
+
+class TestConstruction:
+    def test_insists_on_a_key(self) -> None:
+        with pytest.raises(ValueError, match="api_key"):
+            SecureAI(api_key="")
+
+    def test_trims_a_trailing_slash_rather_than_doubling_it(self) -> None:
+        calls, sai = client(lambda _r: allowed({}))
+        sai.base_url = "https://api.test/"
+        sai.__post_init__()
+        sai.inspect("t", {})
+        assert calls[0]["url"] == "https://api.test/v1/inspect"
+
+
+class TestInspect:
+    def test_sends_the_action_with_outbound_as_the_default(self) -> None:
+        calls, sai = client(lambda _r: allowed({"a": 1}))
+        sai.inspect("http.post", {"a": 1})
+        assert calls[0]["body"]["tool"] == "http.post"
+        assert calls[0]["body"]["direction"] == "outbound"
+
+    def test_names_the_agent_from_the_client(self) -> None:
+        calls, sai = client(lambda _r: allowed({}), agent="nightly-sync")
+        sai.inspect("t", {})
+        assert calls[0]["body"]["agent"] == "nightly-sync"
+
+    def test_sends_the_key_as_a_bearer(self) -> None:
+        calls, sai = client(lambda _r: allowed({}))
+        sai.inspect("t", {})
+        assert calls[0]["headers"]["authorization"] == "Bearer sai_test"
+
+    def test_turns_a_refusal_into_an_error_carrying_the_code(self) -> None:
+        _calls, sai = client(lambda _r: http_error(402, {
+            "error": {"message": "No API access.", "code": "api_access_required"}
+        }))
+        with pytest.raises(SecureAIError) as caught:
+            sai.inspect("t", {})
+        assert caught.value.status == 402
+        assert caught.value.code == "api_access_required"
+
+    def test_survives_a_non_json_body_from_something_in_front_of_the_api(self) -> None:
+        def opener(req, timeout=None):  # noqa: ARG001
+            raise urllib.error.HTTPError(req.full_url, 502, "bad", {}, io.BytesIO(b"<html>"))
+
+        sai = SecureAI(api_key="k", base_url="https://api.test", _opener=opener)
+        with pytest.raises(SecureAIError) as caught:
+            sai.inspect("t", {})
+        assert caught.value.status == 502
+
+
+class TestGuard:
+    def test_calls_the_function_with_the_rewritten_input(self) -> None:
+        """The whole mechanism.
+
+        If this passes while ``send`` receives the caller's original dict, the
+        library protects nothing.
+        """
+        real = {"to": "ana@example.org"}
+        safe = {"to": "person1@example.com"}
+        _calls, sai = client(lambda _r: redacted(safe, {"person1@example.com": "ana@example.org"}))
+
+        seen: list[dict] = []
+
+        def send(payload: dict) -> str:
+            seen.append(payload)
+            return f"sent to {payload['to']}"
+
+        out = sai.guard("email.send", send)(real)
+        assert seen == [safe]
+        assert out == "sent to person1@example.com"
+
+    def test_raises_and_never_calls_the_function_when_refused(self) -> None:
+        _calls, sai = client(lambda _r: blocked())
+        called: list[object] = []
+
+        with pytest.raises(ActionBlocked):
+            sai.guard("http.post", lambda payload: called.append(payload))({})
+        assert called == []
+
+    def test_says_what_was_refused(self) -> None:
+        _calls, sai = client(lambda _r: blocked())
+        with pytest.raises(ActionBlocked, match=r"secret at headers\.authorization"):
+            sai.guard("http.post", lambda _p: "x")({})
+
+    def test_explains_a_denied_tool_differently(self) -> None:
+        _calls, sai = client(lambda _r: blocked(findings=[], tool_denied=True))
+        with pytest.raises(ActionBlocked, match="tool itself is not permitted"):
+            sai.guard("shell.exec", lambda _p: "x")({})
+
+    def test_passes_an_allowed_action_through(self) -> None:
+        payload = {"q": "orders shipped yesterday"}
+        _calls, sai = client(lambda _r: allowed(payload))
+        assert sai.guard("db.query", lambda p: p["q"])(payload) == "orders shipped yesterday"
+
+    def test_works_as_a_decorator(self) -> None:
+        _calls, sai = client(lambda _r: allowed({"a": 1}))
+
+        @sai.guarded("db.query")
+        def run(payload: dict) -> dict:
+            return payload
+
+        assert run({"a": 1}) == {"a": 1}
+        assert run.__name__ == "run"
+
+
+class TestUnreachable:
+    @staticmethod
+    def _dead(req, timeout=None):  # noqa: ARG004
+        raise OSError("network down")
+
+    def test_fails_closed_by_default(self) -> None:
+        sai = SecureAI(api_key="k", _opener=self._dead)
+        called: list[object] = []
+        with pytest.raises(OSError):
+            sai.guard("t", lambda p: called.append(p))({})
+        assert called == []
+
+    def test_fails_open_when_asked(self) -> None:
+        sai = SecureAI(api_key="k", _opener=self._dead, on_unreachable="open")
+        assert sai.guard("t", lambda _p: "done")({}) == "done"
+
+    def test_an_answered_refusal_is_not_an_outage(self) -> None:
+        """Failing open must never wave a 401 through as a blinked network."""
+        _calls, sai = client(
+            lambda _r: http_error(401, {"error": {"message": "bad key", "code": "invalid_api_key"}}),
+            on_unreachable="open",
+        )
+        called: list[object] = []
+        with pytest.raises(SecureAIError):
+            sai.guard("t", lambda p: called.append(p))({})
+        assert called == []
+
+
+class TestPolicyAndTrail:
+    def test_reads_and_replaces_the_policy(self) -> None:
+        calls, sai = client(lambda _r: FakeResponse({"policy": {"version": 1, "fallback": "block", "rules": []}}))
+        sai.set_policy({"fallback": "block", "rules": []})
+        assert calls[0]["method"] == "PUT"
+        assert calls[0]["body"] == {"policy": {"fallback": "block", "rules": []}}
+
+    def test_exempts_a_value(self) -> None:
+        calls, sai = client(lambda _r: FakeResponse({"policy": {}, "added": "@ours.com"}))
+        sai.allow_value("@ours.com")
+        assert calls[0]["url"] == "https://api.test/v1/policy/allow"
+        assert calls[0]["body"] == {"value": "@ours.com"}
+
+    def test_passes_paging_on_the_query_string(self) -> None:
+        calls, sai = client(lambda _r: FakeResponse({"events": [], "cursor": None}))
+        sai.audit(limit=10, cursor="abc")
+        assert calls[0]["url"] == "https://api.test/v1/audit?limit=10&cursor=abc"
+
+    def test_asks_for_the_trail_plainly_when_unpaged(self) -> None:
+        calls, sai = client(lambda _r: FakeResponse({"events": [], "cursor": None}))
+        sai.audit()
+        assert calls[0]["url"] == "https://api.test/v1/audit"
+
+    def test_restores_a_reply(self) -> None:
+        _calls, sai = client(lambda _r: FakeResponse({"text": "call ana@example.org"}))
+        assert sai.restore("call person1@example.com", {"person1@example.com": "ana@example.org"}) \
+            == "call ana@example.org"
+
+
+class TestFindings:
+    def test_a_finding_has_no_place_to_put_a_value(self) -> None:
+        """The trail carries kinds and locations. So does this."""
+        assert set(Finding.__dataclass_fields__) == {"kind", "path", "decision"}
+
+
+class TestGuardTools:
+    def test_wraps_a_framework_tool_in_place(self) -> None:
+        _calls, sai = client(lambda _r: allowed({"a": 1}))
+
+        class Tool:
+            name = "db.query"
+
+            def __init__(self) -> None:
+                self.func = lambda payload: payload
+
+        tool = Tool()
+        sai.guard_tools([tool])
+        assert tool.func({"a": 1}) == {"a": 1}
+
+    def test_leaves_an_unfamiliar_shape_alone_rather_than_raising(self) -> None:
+        _calls, sai = client(lambda _r: allowed({}))
+        odd = object()
+        assert sai.guard_tools([odd]) == [odd]
+
+
+class TestHeldForAPerson:
+    """The branch that did not exist.
+
+    ``guard`` handled ``block`` and nothing else, so an ``approve`` decision
+    fell through to the send. On Python a policy saying an action must wait
+    for a human was not weakened but bypassed, and the agent was told the
+    check had passed.
+    """
+
+    @staticmethod
+    def _held(approval_id="ap1"):
+        return {
+            "decision": "approve",
+            "approvalId": approval_id,
+            "expiresAt": int(time.time() * 1000) + 600_000,
+            "map": {},
+            "findings": [{"kind": "card", "path": "body.note", "decision": "approve"}],
+            "toolDenied": False,
+            "policySource": "account",
+            "auditId": "a1",
+        }
+
+    @staticmethod
+    def _approval(status, **extra):
+        base = {
+            "id": "ap1",
+            "createdAt": int(time.time() * 1000) - 1000,
+            "expiresAt": int(time.time() * 1000) + 600_000,
+            "status": status,
+            "agent": "billing",
+            "tool": "mail.send",
+            "keyId": "k1",
+            "findings": [],
+        }
+        base.update(extra)
+        return {"approval": base}
+
+    def test_waits_then_sends_once_a_person_says_yes(self):
+        seen = []
+
+        def handler(req):
+            if req.full_url.endswith("/v1/inspect"):
+                body = json.loads(req.data.decode("utf-8"))
+                if body.get("approvalId"):
+                    return FakeResponse({
+                        "decision": "allow",
+                        "input": {"note": "go ahead"},
+                        "map": {}, "findings": [], "toolDenied": False,
+                        "policySource": "account", "auditId": "a2",
+                    })
+                return FakeResponse(self._held())
+            return FakeResponse(self._approval("approved"))
+
+        _, sai = client(handler)
+
+        def send(payload):
+            seen.append(payload)
+            return "sent"
+
+        assert sai.guard("mail.send", send)({"note": "original"}) == "sent"
+        # It went, and it went with what came back from the second check.
+        assert seen == [{"note": "go ahead"}]
+
+    def test_does_not_send_when_the_person_says_no(self):
+        def handler(req):
+            if req.full_url.endswith("/v1/inspect"):
+                return FakeResponse(self._held())
+            return FakeResponse(self._approval("denied", note="not this customer"))
+
+        _, sai = client(handler)
+        sent = []
+
+        with pytest.raises(ApprovalRefused) as caught:
+            sai.guard("mail.send", lambda p: sent.append(p))({"note": "x"})
+        assert caught.value.status == "denied"
+        assert "not this customer" in str(caught.value)
+        assert sent == []
+
+    def test_an_expiry_is_a_refusal_not_a_release(self):
+        def handler(req):
+            if req.full_url.endswith("/v1/inspect"):
+                return FakeResponse(self._held())
+            return FakeResponse(self._approval("expired"))
+
+        _, sai = client(handler)
+        sent = []
+        with pytest.raises(ApprovalRefused) as caught:
+            sai.guard("mail.send", lambda p: sent.append(p))({"note": "x"})
+        assert caught.value.status == "expired"
+        assert sent == []
+
+    def test_can_refuse_to_wait_and_hand_the_id_back(self):
+        _, sai = client(lambda req: FakeResponse(self._held()))
+        sent = []
+        with pytest.raises(ApprovalRefused) as caught:
+            sai.guard("mail.send", lambda p: sent.append(p), wait_for_approval=False)({"a": 1})
+        assert caught.value.status == "pending"
+        assert caught.value.approval_id == "ap1"
+        assert sent == []
+
+    def test_a_held_action_with_no_id_is_refused_rather_than_sent(self):
+        held = self._held()
+        del held["approvalId"]
+        _, sai = client(lambda req: FakeResponse(held))
+        sent = []
+        with pytest.raises(ActionBlocked):
+            sai.guard("mail.send", lambda p: sent.append(p))({"a": 1})
+        assert sent == []
+
+    def test_reads_the_queue(self):
+        def handler(req):
+            assert "status=pending" in req.full_url
+            return FakeResponse({"approvals": [self._approval("pending")["approval"]]})
+
+        _, sai = client(handler)
+        queue = sai.approvals(status="pending")
+        assert len(queue) == 1
+        assert queue[0].tool == "mail.send"
+        assert queue[0].status == "pending"
+
+    def test_escapes_the_id_in_the_path(self):
+        calls, sai = client(lambda req: FakeResponse(self._approval("approved")))
+        sai.approval("a/b?c")
+        assert "a%2Fb%3Fc" in calls[0]["url"]
+
+
+class TestARedactWithNothingToSend:
+    """The fallback that braced open.
+
+    The API omits ``input`` only on a block, so on a redact it is always
+    there — until some day it is not. ``guard`` fell back to the caller's own
+    input, which on a redact is the one thing that must not go: it still
+    holds the values the decision had just said to replace.
+    """
+
+    BROKEN = {
+        "decision": "redact",
+        "map": {},
+        "findings": [],
+        "toolDenied": False,
+        "policySource": "account",
+        "auditId": "a9",
+    }
+
+    def test_raises_rather_than_sending_the_original(self):
+        _, sai = client(lambda req: FakeResponse(self.BROKEN))
+        sent = []
+        with pytest.raises(SecureAIError) as caught:
+            sai.guard("mail.send", lambda p: sent.append(p))({"to": "ana@clientfirm.com"})
+        assert "nothing to send" in str(caught.value)
+        assert sent == []
+
+    def test_an_allow_still_passes_the_original_through(self):
+        allowed = dict(self.BROKEN, decision="allow")
+        _, sai = client(lambda req: FakeResponse(allowed))
+        original = {"note": "nothing sensitive"}
+        assert sai.guard("mail.send", lambda p: p)(original) == original