ory-strands 0.12.1__tar.gz

ory_strands-0.12.1/.gitignore

@@ -0,0 +1,36 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.env
+.env.local
+
+# Python (uv workspace under python/)
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+build/
+*.pyc
+
+# Debug logs
+*.log
+
+# Harness sandbox dirs
+.sandbox/
+
+# Staged install-surface repo contents (see scripts/sync-install-surfaces.mjs)
+.install-surfaces/
+
+# Local dev environment (local Ory stack + Verdaccio registry)
+.ory-dev/
+
+# Worktrees for changes
+.worktrees/
+.claude/worktrees/
+
+# Gemini CLI extension assets — materialized at install time from
+# @ory/argus templates. The repo source is the canonical templates;
+# these subdirs are generated wherever the install runs.
+packages/gemini-cli/gemini-extension/skills/
+packages/gemini-cli/gemini-extension/commands/

ory_strands-0.12.1/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: ory-strands
+Version: 0.12.1
+Summary: Ory Agent Security for AWS Strands Agents — per-tool authorization, tracing, and identity propagation via tool-invocation hooks. Built on ory-argus.
+Author: Ory
+License-Expression: Apache-2.0
+Keywords: agent,ai,authorization,aws,bedrock,ory,permissions,strands
+Requires-Python: >=3.10
+Requires-Dist: ory-argus<1,>=0.8
+Requires-Dist: strands-agents>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ory-strands
+
+Ory Agent Security for [AWS Strands Agents](https://strandsagents.com/).
+
+Authorizes every tool call against Ory Permissions via Strands' tool-invocation hooks,
+traces invocations, and propagates user → agent identity — built on
+[`ory-argus`](https://pypi.org/project/ory-argus/).
+
+```bash
+pip install ory-strands
+```
+
+```python
+from strands import Agent
+from ory_strands import OryHooks
+
+agent = Agent(model=..., tools=[search, send_email], hooks=[OryHooks()])
+```
+
+`OryHooks` subscribes to `BeforeToolCallEvent` (authorize) and
+`AfterToolCallEvent` (trace). In **enforce** mode (`ORY_PERMISSION_MODE=enforce`) a
+denied tool is **cancelled** — Strands returns the denial as an error tool result and the
+tool never runs. In **observe** mode (default) the tool runs and a `permission.observe_deny`
+span is recorded.
+
+Credentials come from the shared `~/.config/ory-agent-plugins/config.json`, so a login from
+any Ory harness or `ory-argus login` is reused automatically. See
+[docs/sdk-integrations.md](https://github.com/ory-corp/ory-agent-plugins/blob/main/docs/sdk-integrations.md).

ory_strands-0.12.1/README.md

@@ -0,0 +1,28 @@
+# ory-strands
+
+Ory Agent Security for [AWS Strands Agents](https://strandsagents.com/).
+
+Authorizes every tool call against Ory Permissions via Strands' tool-invocation hooks,
+traces invocations, and propagates user → agent identity — built on
+[`ory-argus`](https://pypi.org/project/ory-argus/).
+
+```bash
+pip install ory-strands
+```
+
+```python
+from strands import Agent
+from ory_strands import OryHooks
+
+agent = Agent(model=..., tools=[search, send_email], hooks=[OryHooks()])
+```
+
+`OryHooks` subscribes to `BeforeToolCallEvent` (authorize) and
+`AfterToolCallEvent` (trace). In **enforce** mode (`ORY_PERMISSION_MODE=enforce`) a
+denied tool is **cancelled** — Strands returns the denial as an error tool result and the
+tool never runs. In **observe** mode (default) the tool runs and a `permission.observe_deny`
+span is recorded.
+
+Credentials come from the shared `~/.config/ory-agent-plugins/config.json`, so a login from
+any Ory harness or `ory-argus login` is reused automatically. See
+[docs/sdk-integrations.md](https://github.com/ory-corp/ory-agent-plugins/blob/main/docs/sdk-integrations.md).

ory_strands-0.12.1/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ory-strands"
+version = "0.12.1"
+description = "Ory Agent Security for AWS Strands Agents — per-tool authorization, tracing, and identity propagation via tool-invocation hooks. Built on ory-argus."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Ory" }]
+keywords = ["ory", "strands", "aws", "bedrock", "authorization", "agent", "ai", "permissions"]
+dependencies = [
+    "ory-argus>=0.8,<1",
+    "strands-agents>=1.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ory_strands"]

ory_strands-0.12.1/src/ory_strands/__init__.py

@@ -0,0 +1,15 @@
+"""Ory Agent Security for AWS Strands Agents.
+
+    from strands import Agent
+    from ory_strands import OryHooks
+
+    agent = Agent(model=..., tools=[...], hooks=[OryHooks()])
+"""
+
+from __future__ import annotations
+
+from .hooks import OryHooks, apply_after, apply_before
+
+__version__ = "0.12.1"
+
+__all__ = ["OryHooks", "apply_before", "apply_after", "__version__"]

ory_strands-0.12.1/src/ory_strands/hooks.py

@@ -0,0 +1,115 @@
+"""Ory Agent Security for AWS Strands Agents.
+
+Strands exposes a first-class per-tool gate through its hook system:
+``BeforeToolCallEvent`` fires before a tool runs (and a hook can **cancel** it by setting
+``event.cancel_tool``), and ``AfterToolCallEvent`` fires after. ``OryHooks`` is a Strands
+``HookProvider`` that authorizes each call against Ory Permissions:
+
+  - allow / observe / fail-open / interactive → do nothing (the tool runs).
+  - deny (enforce) → set ``event.cancel_tool = "Ory: permission denied …"`` so Strands skips
+    the tool and returns the denial as an error tool result.
+
+Register it on the agent:
+
+    from strands import Agent
+    from ory_strands import OryHooks
+
+    agent = Agent(model=..., tools=[...], hooks=[OryHooks()])
+
+All gate logic lives in ``ory_argus``; the hook callbacks are duck-typed (read
+``event.tool_use`` and set ``event.cancel_tool``), so this module imports without
+``strands-agents`` present — only registering the hooks touches the SDK.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ory_argus import OryAgentClient, complete, gate, session_start
+
+HARNESS = "strands"
+
+
+def _tool_name(event: Any) -> str:
+    tu = getattr(event, "tool_use", None) or {}
+    try:
+        return tu.get("name") or "unknown"
+    except AttributeError:
+        return getattr(tu, "name", None) or "unknown"
+
+
+def _tool_input(event: Any) -> Any:
+    tu = getattr(event, "tool_use", None) or {}
+    try:
+        return tu.get("input")
+    except AttributeError:
+        return getattr(tu, "input", None)
+
+
+def apply_before(
+    client: OryAgentClient,
+    event: Any,
+    *,
+    can_block: bool = True,
+    project_url: str | None = None,
+    _session_state: dict | None = None,
+) -> None:
+    """Gate a ``BeforeToolCallEvent``. On deny, sets ``event.cancel_tool``. SDK-free."""
+    state = _session_state if _session_state is not None else {}
+    if not state.get("started"):
+        state["started"] = True
+        try:
+            session_start(client, harness=HARNESS, project_url=project_url)
+        except Exception as err:  # noqa: BLE001 — session gate must never break the agent
+            client.logger.warn("session_start.failed", {"message": str(err)})
+
+    result = gate(
+        client, harness=HARNESS, tool_name=_tool_name(event), tool_args=_tool_input(event), can_block=can_block
+    )
+    if result.blocked:
+        event.cancel_tool = result.denial_message or "Ory: permission denied"
+
+
+def apply_after(client: OryAgentClient, event: Any) -> None:
+    """Record a ``tool.complete`` span for an ``AfterToolCallEvent``. SDK-free."""
+    complete(client, tool_name=_tool_name(event), output=getattr(event, "result", None))
+
+
+class OryHooks:
+    """Strands ``HookProvider`` that gates every tool call through Ory.
+
+    Args:
+        client: An ``OryAgentClient``. Defaults to ``OryAgentClient.from_env("strands")``.
+        can_block: Whether a denied tool is hard-cancelled. Default ``True``.
+        project_url: Override the Ory project URL for the session gates.
+    """
+
+    def __init__(
+        self,
+        *,
+        client: OryAgentClient | None = None,
+        can_block: bool = True,
+        project_url: str | None = None,
+    ) -> None:
+        self._client = client or OryAgentClient.from_env(HARNESS)
+        self._can_block = can_block
+        self._project_url = project_url
+        self._state: dict = {}
+
+    def register_hooks(self, registry: Any, **kwargs: Any) -> None:
+        from strands.hooks.events import AfterToolCallEvent, BeforeToolCallEvent
+
+        registry.add_callback(BeforeToolCallEvent, self._before)
+        registry.add_callback(AfterToolCallEvent, self._after)
+
+    def _before(self, event: Any) -> None:
+        apply_before(
+            self._client, event, can_block=self._can_block,
+            project_url=self._project_url, _session_state=self._state,
+        )
+
+    def _after(self, event: Any) -> None:
+        apply_after(self._client, event)
+
+
+__all__ = ["HARNESS", "OryHooks", "apply_before", "apply_after"]

ory_strands-0.12.1/tests/test_hooks.py

@@ -0,0 +1,70 @@
+"""Hermetic tests for the Strands tool-invocation hooks (mocked Ory, fake events).
+
+Covers the native veto shape (mutating ``event.cancel_tool`` to the denial string) and
+request-shape extraction (``tool_use["name"]`` on both the before and after events). The
+full permission decision matrix is core-owned (``ory-argus/tests/test_adapters.py``).
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from ory_argus.client import PrincipalIdentity
+from ory_argus.testing import (
+    create_mock_client,
+    get_trace_spans,
+    stub_permission_allowed,
+    stub_permission_denied,
+)
+from ory_strands import apply_after, apply_before
+from ory_strands import hooks as hooks_mod
+
+
+@pytest.fixture(autouse=True)
+def _isolate(monkeypatch, tmp_path):
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+    monkeypatch.delenv("ORY_PERMISSION_MODE", raising=False)
+    monkeypatch.setattr(hooks_mod, "session_start", lambda *a, **k: None)
+
+
+def client_with_user():
+    c = create_mock_client(harness="strands")
+    c.set_user_principal(PrincipalIdentity(subject="user:alice"))
+    return c
+
+
+def _before_event(name="search"):
+    return SimpleNamespace(tool_use={"name": name, "input": {"q": 1}}, cancel_tool=None)
+
+
+def test_allow_does_not_cancel():
+    c = client_with_user()
+    stub_permission_allowed(c)
+    ev = _before_event("search")
+    apply_before(c, ev)
+    assert ev.cancel_tool is None
+    invoke = get_trace_spans(c, "tool.invoke")[0]
+    assert invoke.attributes["allowed"] is True
+    # Tool name pulled from the event's ``tool_use["name"]``.
+    assert invoke.attributes["toolName"] == "search"
+
+
+def test_enforce_cancels_tool(monkeypatch):
+    monkeypatch.setenv("ORY_PERMISSION_MODE", "enforce")
+    c = client_with_user()
+    stub_permission_denied(c)
+    ev = _before_event("rm")
+    apply_before(c, ev)
+    # Native veto shape: cancel_tool mutated to the denial string, which Strands uses
+    # to cancel the invocation before the tool runs.
+    assert isinstance(ev.cancel_tool, str) and "permission denied" in ev.cancel_tool.lower()
+    assert get_trace_spans(c, "tool.block")[0].attributes["blocked"] is True
+
+
+def test_after_records_complete():
+    c = client_with_user()
+    ev = SimpleNamespace(tool_use={"name": "search"}, result="ok")
+    apply_after(c, ev)
+    assert get_trace_spans(c, "tool.complete")[0].attributes["toolName"] == "search"

ory_strands-0.12.1/tests/test_realsdk.py

@@ -0,0 +1,35 @@
+"""Real-SDK test: OryHooks registers against the real Strands hook events.
+
+Runs only when ``strands`` is importable; the default workspace venv skips it. Validates the
+thing a fake can't — that ``register_hooks`` subscribes to the *real*
+``BeforeToolCallEvent`` / ``AfterToolCallEvent`` classes (catches an event
+rename / moved import path). No model/backend needed.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+pytest.importorskip("strands")
+
+from strands.hooks.events import AfterToolCallEvent, BeforeToolCallEvent  # noqa: E402
+
+from ory_argus.testing import create_mock_client  # noqa: E402
+from ory_strands import OryHooks  # noqa: E402
+
+
+class _RecordingRegistry:
+    def __init__(self):
+        self.registered: dict = {}
+
+    def add_callback(self, event_type, callback):
+        self.registered[event_type] = callback
+
+
+def test_register_hooks_subscribes_real_events():
+    registry = _RecordingRegistry()
+    OryHooks(client=create_mock_client(harness="strands")).register_hooks(registry)
+    assert BeforeToolCallEvent in registry.registered
+    assert AfterToolCallEvent in registry.registered
+    assert callable(registry.registered[BeforeToolCallEvent])
+    assert callable(registry.registered[AfterToolCallEvent])