node9 0.2.0__py3-none-any.whl

node9/__init__.py

@@ -0,0 +1,20 @@
+"""
+node9 — Execution security for Python AI agents.
+
+Quick start:
+    from node9 import protect
+
+    @protect("write_file")
+    def write_file(path: str, content: str):
+        ...
+
+    @protect("bash")
+    def run_shell(cmd: str):
+        ...
+"""
+
+from ._decorator import protect
+from ._exceptions import ActionDeniedException, DaemonNotFoundError
+
+__all__ = ["protect", "ActionDeniedException", "DaemonNotFoundError"]
+__version__ = "0.1.0"

node9/_client.py

@@ -0,0 +1,108 @@
+"""
+Thin HTTP client — talks to the local Node9 daemon on localhost:7391.
+
+Flow:
+  POST /check  → { id }                      registers the action
+  GET  /wait/:id → { decision, reason? }     blocks until approved / denied
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import time
+import http.client
+import urllib.error
+import urllib.request
+from typing import Any
+
+from ._config import DAEMON_PORT
+from ._exceptions import ActionDeniedException, DaemonNotFoundError
+
+_DAEMON_BASE = f"http://127.0.0.1:{DAEMON_PORT}"
+# The daemon auto-denies after ~55s; we wait slightly longer to get that response.
+_CHECK_TIMEOUT = 5      # seconds to establish connection
+_WAIT_TIMEOUT = 65      # seconds to wait for human decision
+
+
+def _daemon_reachable() -> bool:
+    try:
+        req = urllib.request.Request(f"{_DAEMON_BASE}/settings", method="GET")
+        with urllib.request.urlopen(req, timeout=1.0):
+            return True
+    except urllib.error.URLError:
+        return False
+
+
+def _auto_start_daemon() -> None:
+    """Opt-in: start the daemon in the background when NODE9_AUTO_START=1."""
+    if shutil.which("node9"):
+        cmd = ["node9", "daemon"]
+    elif shutil.which("npx"):
+        cmd = ["npx", "@node9/proxy", "daemon"]
+    else:
+        raise DaemonNotFoundError(DAEMON_PORT)
+    subprocess.Popen(
+        cmd,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    for _ in range(10):
+        time.sleep(0.5)
+        if _daemon_reachable():
+            return
+    raise DaemonNotFoundError(DAEMON_PORT)
+
+
+def _post(path: str, payload: dict) -> dict:
+    # default=str: safely serialize non-JSON-native objects (loggers, datetimes, etc.)
+    data = json.dumps(payload, default=str).encode()
+    req = urllib.request.Request(
+        f"{_DAEMON_BASE}{path}",
+        data=data,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=_CHECK_TIMEOUT) as resp:
+            return json.loads(resp.read())
+    except urllib.error.URLError:
+        raise DaemonNotFoundError(DAEMON_PORT)
+
+
+def _get(path: str) -> dict:
+    req = urllib.request.Request(f"{_DAEMON_BASE}{path}", method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=_WAIT_TIMEOUT) as resp:
+            return json.loads(resp.read())
+    except (urllib.error.URLError, http.client.HTTPException):
+        # URLError = timeout / connection error
+        # HTTPException (incl. RemoteDisconnected) = daemon closed connection → treat as deny
+        return {"decision": "deny", "reason": "Node9 daemon connection timed out or closed."}
+
+
+def evaluate(tool_name: str, args: dict[str, Any]) -> None:
+    """
+    Sends the action to the daemon and blocks until a decision is made.
+    Raises ActionDeniedException if the action is denied.
+    Does nothing if NODE9_SKIP=1 is set (unsafe bypass for testing).
+    Set NODE9_AUTO_START=1 to automatically launch the daemon if it's not running.
+    """
+    if os.environ.get("NODE9_SKIP") == "1":
+        return
+
+    if os.environ.get("NODE9_AUTO_START") == "1" and not _daemon_reachable():
+        _auto_start_daemon()
+
+    result = _post("/check", {"toolName": tool_name, "args": args, "cwd": os.getcwd(), "agent": "Python SDK"})
+    request_id = result.get("id")
+    if not request_id:
+        raise RuntimeError(f"[Node9] Unexpected daemon response: {result}")
+
+    print(f"🛡️  Node9: waiting for approval of '{tool_name}'...", flush=True)
+    decision_result = _get(f"/wait/{request_id}")
+    decision = decision_result.get("decision", "deny")
+
+    if decision != "allow":
+        reason = decision_result.get("reason", "Denied by Node9 policy")
+        raise ActionDeniedException(tool_name, reason)

node9/_config.py

@@ -0,0 +1,3 @@
+import os
+
+DAEMON_PORT = int(os.environ.get("NODE9_DAEMON_PORT", "7391"))

node9/_decorator.py

@@ -0,0 +1,65 @@
+import asyncio
+import functools
+import inspect
+from typing import Any, Callable, Optional
+
+from ._client import evaluate
+
+
+def _capture_args(func: Callable, params: Optional[Callable], *args: Any, **kwargs: Any) -> dict:
+    if params is not None:
+        return params(*args, **kwargs)
+    sig = inspect.signature(func)
+    bound = sig.bind(*args, **kwargs)
+    bound.apply_defaults()
+    return dict(bound.arguments)
+
+
+def protect(
+    tool_name: Optional[str] = None,
+    *,
+    params: Optional[Callable[..., dict]] = None,
+):
+    """
+    Decorator that intercepts a function call and asks Node9 for approval.
+
+    Works with both sync and async functions.
+
+    Usage:
+        @protect("write_file")
+        def write_file(path: str, content: str): ...
+
+        @protect("bash", params=lambda cmd, **_: {"command": cmd})
+        async def run_shell(cmd: str): ...
+
+    If no `params` lambda is provided, all arguments are captured automatically
+    using inspect.signature — no configuration needed.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        name = tool_name or func.__name__
+
+        if inspect.iscoroutinefunction(func):
+            @functools.wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                captured = _capture_args(func, params, *args, **kwargs)
+                # Run blocking HTTP call in a thread to avoid blocking the event loop
+                await asyncio.to_thread(evaluate, name, captured)
+                return await func(*args, **kwargs)
+            return async_wrapper
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            captured = _capture_args(func, params, *args, **kwargs)
+            evaluate(name, captured)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    # Support both @protect and @protect("name") usage
+    if callable(tool_name):
+        func = tool_name
+        tool_name = func.__name__
+        return decorator(func)
+
+    return decorator

node9/_exceptions.py

@@ -0,0 +1,21 @@
+class ActionDeniedException(Exception):
+    """Raised when Node9 blocks an agent action."""
+
+    def __init__(self, tool_name: str, reason: str = "Denied by Node9 policy"):
+        self.tool_name = tool_name
+        self.reason = reason
+        # negotiation: ready-made string for feeding back to the LLM
+        self.negotiation = f"Action '{tool_name}' was blocked by Node9: {reason}. Choose a different approach."
+        super().__init__(f"[Node9] Action '{tool_name}' was blocked: {reason}")
+
+
+class DaemonNotFoundError(Exception):
+    """Raised when the Node9 daemon is not reachable."""
+
+    def __init__(self, port: int = 7391):
+        super().__init__(
+            f"Node9 daemon not found on localhost:{port}.\n"
+            f"To enable execution security, run:\n"
+            f"  npx @node9/proxy daemon\n"
+            f"or set NODE9_SKIP=1 to bypass (unsafe)."
+        )

node9-0.2.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: node9
+Version: 0.2.0
+Summary: Execution security for Python AI agents — seatbelt for LangChain, CrewAI, and plain Python.
+Project-URL: Homepage, https://node9.ai
+Project-URL: Repository, https://github.com/node9-ai/node9-python
+Project-URL: Documentation, https://node9.ai/docs
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,ai,crewai,langchain,llm,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# node9-python
+
+Execution security for Python AI agents — one decorator, zero config.
+
+Works with any framework: plain Python, LangChain, CrewAI, LangGraph, or custom agents.
+
+## Install
+
+```bash
+pip install node9
+```
+
+## Quick Start
+
+**1. Start the Node9 daemon** (ships with `@node9/proxy`):
+
+```bash
+npx @node9/proxy daemon
+```
+
+**2. Add `@protect` to any function your agent calls:**
+
+```python
+from node9 import protect, ActionDeniedException
+
+@protect
+def write_file(path: str, content: str) -> None:
+    with open(path, "w") as f:
+        f.write(content)
+
+@protect("bash")
+def run_shell(command: str) -> str:
+    import subprocess
+    return subprocess.check_output(command, shell=True, text=True)
+
+# When your agent calls this, Node9 intercepts it and asks for approval.
+# The call blocks until a human approves or denies — in the dashboard or Slack.
+try:
+    write_file("/etc/hosts", "malicious content")
+except ActionDeniedException as e:
+    print(f"Blocked: {e}")
+```
+
+That's it. All function arguments are captured automatically — no config needed.
+
+## How It Works
+
+```
+Agent calls write_file()
+       ↓
+  @protect intercepts
+       ↓
+  POST /check → Node9 daemon (localhost:7391)
+       ↓
+  Daemon shows approval popup / sends Slack message
+       ↓
+  Human approves or denies
+       ↓
+  Function runs (or ActionDeniedException is raised)
+```
+
+## Async Support
+
+`@protect` works with `async def` out of the box. The blocking HTTP call runs in a thread so it never freezes your event loop:
+
+```python
+@protect("write_file")
+async def write_file(path: str, content: str) -> str:
+    async with aiofiles.open(path, "w") as f:
+        await f.write(content)
+    return f"Written to {path}"
+```
+
+This makes it compatible with LangGraph, FastMCP, and any other async agent framework.
+
+## Custom Tool Name
+
+By default, the tool name sent to Node9 is the function name. Override it:
+
+```python
+@protect("postgres_query")
+def execute_sql(sql: str, db: str = "prod") -> list:
+    ...
+```
+
+## Custom Params
+
+Control exactly what gets sent to the approval UI:
+
+```python
+@protect("deploy", params=lambda service, env="prod", **_: {"service": service, "env": env})
+def deploy(service: str, env: str = "prod", dry_run: bool = False) -> str:
+    ...
+```
+
+## Handling Denials in LLM Feedback Loops
+
+`ActionDeniedException` has a `negotiation` property — a ready-made string you can feed back to the LLM so it can try a different approach instead of crashing:
+
+```python
+try:
+    delete_file("/etc/hosts")
+except ActionDeniedException as e:
+    # e.negotiation = "Action 'delete_file' was blocked by Node9: Too dangerous. Choose a different approach."
+    response = llm.invoke(e.negotiation)
+```
+
+## Framework Examples
+
+### LangChain
+
+```python
+from langchain.tools import BaseTool
+from node9 import protect
+
+class WriteFileTool(BaseTool):
+    name = "write_file"
+    description = "Write content to a file."
+
+    @protect("write_file")
+    def _run(self, path: str, content: str) -> str:
+        with open(path, "w") as f:
+            f.write(content)
+        return f"Written to {path}"
+```
+
+### CrewAI
+
+```python
+from crewai.tools import tool
+from node9 import protect
+
+@tool("write_file")
+@protect("write_file")
+def write_file(path: str, content: str) -> str:
+    """Write content to a file."""
+    with open(path, "w") as f:
+        f.write(content)
+    return f"Written to {path}"
+```
+
+See [`examples/`](examples/) for full runnable examples.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `NODE9_DAEMON_PORT` | `7391` | Daemon port |
+| `NODE9_AUTO_START` | — | Set to `1` to auto-launch the daemon if it's not running |
+| `NODE9_SKIP` | — | Set to `1` to bypass all checks (unsafe — for tests only) |
+
+## License
+
+Apache-2.0

node9-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+node9/__init__.py,sha256=SOTNlhXd1yPbpQZbuLU2eQVNXF4dJJJZ3OIQUi4R5n8,445
+node9/_client.py,sha256=-UEYqYhI-1xJq_uWFA6YJpfqiI8SrhlLffKF5mkHMjU,3771
+node9/_config.py,sha256=myMbx4931AX3u9GtdE___0mY8406wmZMU2Ovh5BvokY,74
+node9/_decorator.py,sha256=QFjji5D_3Oh0Y_y78jAoXya8JoimDBQCL_IcFbcLL7Y,2018
+node9/_exceptions.py,sha256=QR_TZFbZzzf1Ys81L-8Rh3vmqP31Yc1bib2xgoz16QA,885
+node9-0.2.0.dist-info/METADATA,sha256=1I8HjWL10ZEbI9NtjyamaUoSfAcR8aFtMb5Pa_528XI,4693
+node9-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+node9-0.2.0.dist-info/licenses/LICENSE,sha256=qrLHZ6kj7-VPCZtYqV-QeckNfeA0QjEc4SqTXjvuC5o,10322
+node9-0.2.0.dist-info/RECORD,,

node9-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

node9-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,183 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other transformations
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and the Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any Contribution
+      embodied within the Work constitutes direct or contributory patent
+      infringement, then any patent licenses granted to You under this License
+      for that Work shall terminate as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, reproduce, modify,
+      prepare Derivative Works of, convert to other formats, and distribute
+      the contributions, provided such additional grant of rights does not
+      conflict with the terms and conditions of this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer such
+      obligations only on Your own behalf and on Your sole responsibility,
+      not on behalf of any other Contributor, and only if You agree to
+      indemnify, defend, and hold each Contributor harmless for any
+      liability incurred by, or claims asserted against, such Contributor
+      by reason of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Node9 AI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.