ory-argus 0.13.9__tar.gz

ory_argus-0.13.9/.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_argus-0.13.9/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: ory-argus
+Version: 0.13.9
+Summary: Ory Agent Security core for Python — authentication, per-tool authorization, tracing, and identity propagation for Agent SDK integrations. Python sibling of the TypeScript @ory/argus.
+Author: Ory
+License-Expression: Apache-2.0
+Keywords: agent,ai,authentication,authorization,ory,permissions,tracing
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24
+Requires-Dist: opentelemetry-api>=1.20
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20
+Requires-Dist: opentelemetry-sdk>=1.20
+Requires-Dist: ory-client<2,>=1.22
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ory-argus (Python)
+
+Ory Agent Security core for Python — the sibling of the TypeScript
+[`@ory/argus`](https://www.npmjs.com/package/@ory/argus) package.
+
+It provides the shared primitives that the Ory **Agent SDK integrations**
+(LangChain, OpenAI Agents, Pydantic AI, Microsoft Agent Framework, CrewAI,
+LlamaIndex, Google ADK, AWS Strands, Google Antigravity) build on:
+
+1. **Authenticate** the session on startup (user PKCE login + agent OAuth2 identity).
+2. **Authorize** every tool call against Ory Permissions (Zanzibar-style relation checks).
+3. **Trace** every tool invocation as a structured span (OTLP + NDJSON).
+4. **Propagate identity** through the user → agent → sub-agent delegation chain.
+
+## Interop with the TypeScript core
+
+`ory-argus` reads and writes the **same** shared config file as every TS harness
+plugin — `~/.config/ory-agent-plugins/config.json` (XDG / `%APPDATA%` aware). A
+user who logs in via a TS coding-agent harness has those credentials transparently
+reused by a Python SDK integration, and vice-versa. This package never invents a
+second config location; use `get_data_dir()` / `get_config_path()`.
+
+Install: `pip install ory-argus` · Console script: `ory-argus`

ory_argus-0.13.9/README.md

@@ -0,0 +1,23 @@
+# ory-argus (Python)
+
+Ory Agent Security core for Python — the sibling of the TypeScript
+[`@ory/argus`](https://www.npmjs.com/package/@ory/argus) package.
+
+It provides the shared primitives that the Ory **Agent SDK integrations**
+(LangChain, OpenAI Agents, Pydantic AI, Microsoft Agent Framework, CrewAI,
+LlamaIndex, Google ADK, AWS Strands, Google Antigravity) build on:
+
+1. **Authenticate** the session on startup (user PKCE login + agent OAuth2 identity).
+2. **Authorize** every tool call against Ory Permissions (Zanzibar-style relation checks).
+3. **Trace** every tool invocation as a structured span (OTLP + NDJSON).
+4. **Propagate identity** through the user → agent → sub-agent delegation chain.
+
+## Interop with the TypeScript core
+
+`ory-argus` reads and writes the **same** shared config file as every TS harness
+plugin — `~/.config/ory-agent-plugins/config.json` (XDG / `%APPDATA%` aware). A
+user who logs in via a TS coding-agent harness has those credentials transparently
+reused by a Python SDK integration, and vice-versa. This package never invents a
+second config location; use `get_data_dir()` / `get_config_path()`.
+
+Install: `pip install ory-argus` · Console script: `ory-argus`

ory_argus-0.13.9/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ory-argus"
+version = "0.13.9"
+description = "Ory Agent Security core for Python — authentication, per-tool authorization, tracing, and identity propagation for Agent SDK integrations. Python sibling of the TypeScript @ory/argus."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Ory" }]
+keywords = ["ory", "authorization", "authentication", "agent", "ai", "tracing", "permissions"]
+dependencies = [
+    "ory-client>=1.22,<2",
+    "opentelemetry-api>=1.20",
+    "opentelemetry-sdk>=1.20",
+    "opentelemetry-exporter-otlp-proto-http>=1.20",
+    "httpx>=0.24",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "ruff>=0.6"]
+
+[project.scripts]
+ory-argus = "ory_argus.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ory_argus"]

ory_argus-0.13.9/src/ory_argus/__init__.py

@@ -0,0 +1,238 @@
+"""Ory Agent Security core for Python.
+
+Python sibling of the TypeScript ``@ory/argus`` core. Provides the same
+authentication, per-tool authorization, tracing, and identity-propagation
+primitives, reading and writing the *same* shared config file so credentials
+established in one ecosystem are reusable from the other.
+
+Public API is re-exported from the submodules as they land. ``config`` is the
+cross-language interop contract and is available now.
+"""
+
+from __future__ import annotations
+
+from .adapters import (
+    GateResult,
+    SessionStartResult,
+    complete,
+    gate,
+    guarded_tool,
+    register_subagent,
+    resolve_namespace,
+    session_start,
+)
+from .agent_auth import (
+    AgentCredentials,
+    SubAgentIdentity,
+    ensure_agent_identity,
+    ensure_subagent_identity,
+    register_agent_client,
+    resolve_agent_credentials,
+)
+from .auth import (
+    DEFAULT_LOGIN_TIMEOUT_MS,
+    LOOPBACK_PORTS,
+    PkceLoginOutcome,
+    detect_headless,
+    pkce_login,
+    refresh_access_token,
+)
+from .auth_store import (
+    clear_tokens,
+    is_expired,
+    load_tokens,
+    save_tokens,
+)
+from .client import OryAgentClient, PrincipalIdentity, extract_ory_request_id
+from .config import (
+    DELETE,
+    OryAgentCredentialsBlock,
+    OryAgentDynamicCredentials,
+    OryOAuth2Tokens,
+    OryPluginConfig,
+    OryUserCredentials,
+    PermissionMode,
+    ResolvedConfig,
+    config_prompt_message,
+    get_config_path,
+    get_data_dir,
+    get_harness_data_dir,
+    load_config,
+    mutate_config,
+    resolve_config,
+    save_config,
+)
+from .denial import (
+    DenialContext,
+    OryDenialError,
+    alert_attributes,
+    format_alert_message,
+    format_denial_message,
+    format_denial_summary,
+)
+from .lifecycle import (
+    HARNESS_LIFECYCLE_MAP,
+    LifecyclePhase,
+    classify_lifecycle,
+    is_tool_execution_phase,
+    is_user_facing_phase,
+)
+from .logger import DebugLogger, redact_log_data
+from .otel import OtlpExporter, SpanExporter, otlp_exporter_from_env
+from .permissions import (
+    ModeDecision,
+    PermissionDecision,
+    apply_permission_mode,
+    check_and_decide,
+    gate_tool_call,
+)
+from .subject import (
+    SubjectId,
+    SubjectSetRef,
+    UserSubjectRef,
+    apply_subject_to_check_kwargs,
+    resolve_user_subject,
+    subject_label,
+)
+from .tool_catalog import (
+    ALL_TOOLS,
+    HARNESS_TOOL_CATALOG,
+    INTERACTIVE_TOOL_CATALOG,
+    KNOWN_HARNESSES,
+    get_interactive_tool_catalog,
+    get_tool_catalog,
+    is_interactive_tool,
+)
+from .tracer import (
+    ActiveSpan,
+    SpanOptions,
+    Tracer,
+    TracerContext,
+    TraceSpan,
+    derive_trace_id,
+    format_span,
+)
+from .types import (
+    BatchPermissionResult,
+    OAuth2TokenInfo,
+    OryError,
+    OryErrorCode,
+    PermissionCheck,
+    PermissionResult,
+    SessionInfo,
+    SubjectSet,
+)
+from .user_login import UserLoginDecision, ensure_user_authenticated
+
+__version__ = "0.13.9"
+
+__all__ = [
+    "__version__",
+    # config
+    "DELETE",
+    "PermissionMode",
+    "OryOAuth2Tokens",
+    "OryUserCredentials",
+    "OryAgentDynamicCredentials",
+    "OryAgentCredentialsBlock",
+    "OryPluginConfig",
+    "ResolvedConfig",
+    "get_data_dir",
+    "get_harness_data_dir",
+    "get_config_path",
+    "load_config",
+    "save_config",
+    "mutate_config",
+    "resolve_config",
+    "config_prompt_message",
+    # client
+    "OryAgentClient",
+    "PrincipalIdentity",
+    "extract_ory_request_id",
+    # logger
+    "DebugLogger",
+    "redact_log_data",
+    # tracer / otel
+    "Tracer",
+    "TraceSpan",
+    "ActiveSpan",
+    "SpanOptions",
+    "TracerContext",
+    "derive_trace_id",
+    "format_span",
+    "SpanExporter",
+    "OtlpExporter",
+    "otlp_exporter_from_env",
+    # types
+    "SessionInfo",
+    "OAuth2TokenInfo",
+    "PermissionCheck",
+    "SubjectSet",
+    "PermissionResult",
+    "BatchPermissionResult",
+    "OryError",
+    "OryErrorCode",
+    # permissions
+    "PermissionDecision",
+    "ModeDecision",
+    "gate_tool_call",
+    "check_and_decide",
+    "apply_permission_mode",
+    # subject
+    "UserSubjectRef",
+    "SubjectId",
+    "SubjectSetRef",
+    "resolve_user_subject",
+    "subject_label",
+    "apply_subject_to_check_kwargs",
+    # denial
+    "DenialContext",
+    "OryDenialError",
+    "alert_attributes",
+    "format_denial_message",
+    "format_denial_summary",
+    "format_alert_message",
+    # tool catalog
+    "HARNESS_TOOL_CATALOG",
+    "INTERACTIVE_TOOL_CATALOG",
+    "KNOWN_HARNESSES",
+    "ALL_TOOLS",
+    "get_tool_catalog",
+    "get_interactive_tool_catalog",
+    "is_interactive_tool",
+    # lifecycle
+    "LifecyclePhase",
+    "HARNESS_LIFECYCLE_MAP",
+    "classify_lifecycle",
+    "is_user_facing_phase",
+    "is_tool_execution_phase",
+    # auth — user
+    "ensure_user_authenticated",
+    "UserLoginDecision",
+    "pkce_login",
+    "PkceLoginOutcome",
+    "refresh_access_token",
+    "detect_headless",
+    "LOOPBACK_PORTS",
+    "DEFAULT_LOGIN_TIMEOUT_MS",
+    "load_tokens",
+    "save_tokens",
+    "clear_tokens",
+    "is_expired",
+    # auth — agent
+    "ensure_agent_identity",
+    "ensure_subagent_identity",
+    "resolve_agent_credentials",
+    "register_agent_client",
+    "AgentCredentials",
+    "SubAgentIdentity",
+    # adapters (the thin-integration surface)
+    "session_start",
+    "gate",
+    "complete",
+    "register_subagent",
+    "guarded_tool",
+    "resolve_namespace",
+    "SessionStartResult",
+    "GateResult",
+]

ory_argus-0.13.9/src/ory_argus/adapters.py

@@ -0,0 +1,308 @@
+"""Shared adapter primitives for Agent SDK integrations.
+
+Every SDK integration is a thin translation between the SDK's hook signature and these
+primitives, so the span boilerplate and the session/sub-agent sequencing live in exactly
+one place (the Python sibling of the TS ``packages/core/src/adapters/`` extraction):
+
+  - :func:`session_start` — run the user + agent auth gates and write the user→agent
+    delegation tuple. Returns whether the session may proceed.
+  - :func:`gate` — resolve the subject, run :func:`gate_tool_call`, record the
+    ``tool.invoke`` / ``tool.block`` spans, and return a normalized :class:`GateResult`.
+  - :func:`complete` — record the ``tool.complete`` span.
+  - :func:`register_subagent` — resolve a sub-agent identity and write the
+    agent→subagent delegation tuple.
+  - :func:`guarded_tool` — wrap a plain ``execute(args)`` callable with gate+complete, for
+    SDKs whose only veto point is the tool boundary (CrewAI, LlamaIndex, Vercel).
+
+Every primitive is best-effort and fail-open: identity/delegation failures are logged and
+swallowed, and a network/rate-limit error on a permission check lets the tool proceed.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from .agent_auth import ensure_agent_identity, ensure_subagent_identity
+from .config import resolve_config
+from .denial import DenialContext, OryDenialError, alert_attributes, format_denial_message
+from .permissions import PermissionDecision, gate_tool_call
+from .subject import apply_subject_to_check_kwargs, resolve_user_subject, subject_label
+from .types import PermissionCheck
+from .user_login import ensure_user_authenticated
+
+if TYPE_CHECKING:
+    from .client import OryAgentClient
+
+
+def resolve_namespace() -> str:
+    return os.environ.get("ORY_PERMISSION_NAMESPACE") or "AgentTools"
+
+
+# ─── Session start ────────────────────────────────────────────────────
+
+
+@dataclass
+class SessionStartResult:
+    proceed: bool
+    user_mode: str
+    user_reason: str
+    agent_kind: str
+
+
+def session_start(
+    client: OryAgentClient,
+    *,
+    harness: str,
+    allow_block: bool = False,
+    project_url: str | None = None,
+    bin_name: str | None = None,
+    user_login: Callable[..., Any] = ensure_user_authenticated,
+    agent_gate: Callable[..., Any] = ensure_agent_identity,
+) -> SessionStartResult:
+    """Run both auth gates and write the user→agent delegation tuple.
+
+    ``allow_block`` is advisory for most SDK integrations (an agent constructed in-process
+    can't be prevented from starting), but the user gate still runs, refreshes tokens, and
+    records the ``user.auth`` span. The agent gate and delegation write always run.
+    """
+    resolved_url = project_url or resolve_config().project_url
+    decision = user_login(client, bin_name=bin_name or f"ory-{harness}", harness=harness, allow_block=allow_block)
+    creds = agent_gate(client, project_url=resolved_url, harness=harness)
+    _record_user_delegates_agent(client)
+    return SessionStartResult(
+        proceed=getattr(decision, "proceed", True),
+        user_mode=getattr(decision, "mode", "disabled"),
+        user_reason=getattr(decision, "reason", ""),
+        agent_kind=getattr(creds, "kind", "none"),
+    )
+
+
+def _record_user_delegates_agent(client: OryAgentClient) -> None:
+    user = client.user_principal.subject
+    agent = client.agent_principal.subject
+    if not user or not agent:
+        return
+    try:
+        client.create_relationship(
+            PermissionCheck(
+                namespace=resolve_namespace(),
+                object=f"agent:{agent}",
+                relation="delegate",
+                subject_id=f"user:{user}",
+            ),
+            span_attributes={"delegation": "user-to-agent"},
+        )
+    except Exception as err:  # noqa: BLE001 — delegation tuples are audit-only
+        client.logger.warn("delegation.user_to_agent.failed", {"message": str(err)})
+
+
+# ─── Sub-agent registration ───────────────────────────────────────────
+
+
+def register_subagent(
+    client: OryAgentClient,
+    *,
+    harness: str,
+    sub_agent_type: str,
+    project_url: str | None = None,
+    subagent_gate: Callable[..., Any] = ensure_subagent_identity,
+) -> None:
+    """Resolve a sub-agent identity and write the agent→subagent delegation tuple."""
+    resolved_url = project_url or resolve_config().project_url
+    try:
+        identity = subagent_gate(client, sub_agent_type=sub_agent_type, project_url=resolved_url, harness=harness)
+    except Exception as err:  # noqa: BLE001
+        client.logger.warn("subagent.identity.failed", {"subAgentType": sub_agent_type, "message": str(err)})
+        return
+    if getattr(identity, "kind", "none") != "dynamic" or not identity.subject:
+        return
+    agent = client.agent_principal.subject
+    if not agent:
+        return
+    try:
+        client.create_relationship(
+            PermissionCheck(
+                namespace=resolve_namespace(),
+                object=f"subagent:{identity.subject}",
+                relation="delegate",
+                subject_id=f"agent:{agent}",
+            ),
+            span_attributes={"delegation": "agent-to-subagent", "subAgentType": sub_agent_type},
+        )
+    except Exception as err:  # noqa: BLE001
+        client.logger.warn("delegation.agent_to_subagent.failed", {"subAgentType": sub_agent_type, "message": str(err)})
+
+
+# ─── Tool gate ────────────────────────────────────────────────────────
+
+
+@dataclass
+class GateResult:
+    """Normalized outcome of :func:`gate`.
+
+    ``proceed`` is True unless the tool was hard-denied in enforce mode. ``blocked`` is True
+    only for that deny. ``decision`` carries the raw :class:`PermissionDecision`.
+    """
+
+    proceed: bool
+    blocked: bool
+    decision: PermissionDecision
+    subject: str
+    namespace: str
+    denial_message: str | None = None
+
+    @property
+    def kind(self) -> str:
+        return self.decision.kind
+
+
+def gate(
+    client: OryAgentClient,
+    *,
+    harness: str,
+    tool_name: str,
+    tool_args: Any = None,
+    subject_fallback: str | None = None,
+    can_block: bool = True,
+    extra_span_attributes: dict[str, Any] | None = None,
+) -> GateResult:
+    """Authorize a tool call, record spans, and return a normalized :class:`GateResult`.
+
+    ``can_block`` marks whether the calling integration can actually stop the tool (sets the
+    ``blocked`` alert attribute accordingly). Records ``tool.invoke`` on allow/observe and
+    ``tool.block`` on deny/observe — identical span semantics to the TS harness plugins.
+    """
+    namespace = resolve_namespace()
+    subject_ref = resolve_user_subject(client, subject_fallback)
+    label = subject_label(subject_ref)
+    check = PermissionCheck(
+        namespace=namespace,
+        object=tool_name,
+        relation="use",
+        **apply_subject_to_check_kwargs(subject_ref),
+    )
+    span_attrs = {"toolName": tool_name, **(extra_span_attributes or {})}
+
+    # Audit-only kill switch: Ory is disabled entirely — no permission check.
+    # Record only the audit ``tool.invoke`` span (same span semantics as the
+    # harness plugins' audit-only short-circuit) and pass the tool through.
+    resolved = resolve_config()
+    if resolved.audit_only:
+        client.tracer.record("tool.invoke", "ok", attributes=span_attrs)
+        decision = PermissionDecision(
+            kind="allow",
+            mode=resolved.permission_mode,
+            span_attributes={"permissionMode": resolved.permission_mode},
+        )
+        return GateResult(True, False, decision, label, namespace)
+
+    decision = gate_tool_call(
+        client, harness=harness, tool_name=tool_name, check=check, span_attributes=span_attrs
+    )
+    decision_attrs = decision.span_attributes
+
+    if decision.kind == "audit_only":
+        # Kill switch: Ory is disabled. Audit the invocation, skip the check.
+        client.tracer.record("tool.invoke", "ok", attributes={**span_attrs, "auditOnly": True})
+        return GateResult(True, False, decision, label, namespace)
+
+    if decision.kind == "interactive":
+        # user.interaction already recorded by gate_tool_call; pass through.
+        return GateResult(True, False, decision, label, namespace)
+
+    if decision.kind == "fail_open":
+        client.logger.warn(
+            "permission.fail_open",
+            {"tool": tool_name, "code": decision.error.code if decision.error else "unknown"},
+        )
+        return GateResult(True, False, decision, label, namespace)
+
+    if decision.kind == "allow":
+        client.tracer.record("tool.invoke", "ok", attributes={**span_attrs, **decision_attrs, "allowed": True})
+        return GateResult(True, False, decision, label, namespace)
+
+    if decision.kind == "observe":
+        client.tracer.record(
+            "tool.block", "denied",
+            attributes={**span_attrs, **decision_attrs, "allowed": False, **alert_attributes(False)},
+        )
+        client.tracer.record(
+            "tool.invoke", "ok",
+            attributes={**span_attrs, **decision_attrs, "allowed": False, "observed": True},
+        )
+        return GateResult(True, False, decision, label, namespace)
+
+    # deny
+    client.tracer.record(
+        "tool.block", "denied",
+        attributes={**span_attrs, **decision_attrs, "allowed": False, **alert_attributes(can_block)},
+    )
+    message = format_denial_message(DenialContext(tool=tool_name, subject_id=label, namespace=namespace))
+    client.logger.warn("tool.denied", {"tool": tool_name, "subjectId": label})
+    return GateResult(False, can_block, decision, label, namespace, denial_message=message)
+
+
+def complete(
+    client: OryAgentClient,
+    *,
+    tool_name: str,
+    output: Any = None,
+    extra_span_attributes: dict[str, Any] | None = None,
+    status: str = "ok",
+) -> None:
+    """Record a ``tool.complete`` span. Never blocks."""
+    attrs: dict[str, Any] = {"toolName": tool_name, **(extra_span_attributes or {})}
+    if output is not None:
+        attrs["hasOutput"] = True
+    client.tracer.record("tool.complete", status, attributes=attrs)  # type: ignore[arg-type]
+
+
+def denial_error(result: GateResult, tool_name: str) -> OryDenialError:
+    """Build an :class:`OryDenialError` from a denied :class:`GateResult`."""
+    return OryDenialError(
+        DenialContext(tool=tool_name, subject_id=result.subject, namespace=result.namespace)
+    )
+
+
+def guarded_tool(
+    client: OryAgentClient,
+    *,
+    harness: str,
+    tool_name: str,
+    execute: Callable[[Any], Any],
+    can_block: bool = True,
+):
+    """Wrap a plain ``execute(args)`` callable with gate + complete.
+
+    On allow/observe/fail-open/interactive the wrapped tool runs and a ``tool.complete``
+    span is recorded. On a hard deny it raises :class:`OryDenialError` (the veto mechanism
+    for tool-boundary SDKs). Returns a callable with the same ``(args)`` signature.
+    """
+
+    def wrapped(args: Any = None):
+        result = gate(client, harness=harness, tool_name=tool_name, tool_args=args, can_block=can_block)
+        if result.blocked:
+            raise OryDenialError(
+                DenialContext(tool=tool_name, subject_id=result.subject, namespace=result.namespace)
+            )
+        output = execute(args)
+        complete(client, tool_name=tool_name, output=output)
+        return output
+
+    return wrapped
+
+
+__all__ = [
+    "SessionStartResult",
+    "GateResult",
+    "resolve_namespace",
+    "session_start",
+    "register_subagent",
+    "gate",
+    "complete",
+    "guarded_tool",
+    "denial_error",
+]