@macaw-ai/client 0.0.0-stage → 0.9.10

package/payload/secureAI/examples/phishing-resistance/README.md

@@ -0,0 +1,124 @@
+# Phishing-Resistance Examples
+
+These examples demonstrate **login-strength gating**: a tool runs only if the
+human behind the agent authenticated with a **phishing-resistant** method
+(passkey / hardware key / WebAuthn).
+
+## What Is Phishing-Resistance?
+
+When a user authenticates, their token carries an `amr` (authentication
+methods) claim describing *how* they logged in — `fido`/`hwk` for a passkey,
+`pwd` for a password. At registration the control plane reads `amr` and, if the
+login was phishing-resistant, mints an **internal** `phishing_resistant` grant
+for that agent. A policy that lists `phishing_resistant` then allows or denies
+with **no human in the loop and no waiting**.
+
+This is the opposite of an [external attestation](../attestations/) like
+`trade-approved`, which *blocks* while a manager approves:
+
+| | `phishing_resistant` | `trade-approved` |
+|---|---|---|
+| decided by | the control plane, at login, from `amr` | a human approver (role:manager) |
+| flow | deny-if-absent, immediate | blocks and waits |
+| console | an **Active Grant** (never a pending request) | a pending HITL request |
+| reusable | yes (`one_time=False`, TTL = token lifetime) | configurable |
+
+**Use cases:** gating high-risk tools behind hardware-backed auth; requiring
+step-up/passkey login before sensitive operations; layering a login-strength
+check in front of a human approval.
+
+## Getting a token
+
+Both examples read a token from `get_token.py`, which signs you in to Entra and
+saves an id_token that carries `amr`:
+
+```bash
+python get_token.py                       # a browser opens — choose how to sign in:
+                                          #   PASSKEY  -> amr:["fido"]      -> ALLOW
+                                          #   PASSWORD -> amr:["pwd","mfa"] -> DENY
+export ALICE_TOKEN=$(cat ~/.macaw_demo_token)
+```
+
+## Examples
+
+### Example 1a: Login gating (Alice alone)
+
+The simplest form — one agent, one gate, **no approver**. Run it twice, changing
+only how you log in.
+
+| File | Role | What It Does |
+|------|------|--------------|
+| `1a_login_alice.py` | User | Invokes a `phishing_resistant`-gated tool; allowed or denied by login method |
+
+**Key concepts:**
+- The only gate: `"attestations": ["phishing_resistant"]`
+- No `constraints` block, no approver, no blocking — the decision is immediate
+- `PASSKEY` → allowed; `PASSWORD` → denied
+
+**Run:**
+```bash
+python get_token.py            # sign in with a PASSKEY
+export ALICE_TOKEN=$(cat ~/.macaw_demo_token)
+python 1a_login_alice.py       # ALLOWED
+
+# now re-run get_token.py, sign in with a PASSWORD, and repeat:
+python 1a_login_alice.py       # DENIED at phishing_resistant
+```
+
+### Example 1b: Precondition to human approval (Alice + Bob)
+
+Builds on the [alice/bob trade example](../attestations/) by **layering two
+gates** on the same trade: `phishing_resistant` (internal, first) then
+`trade-approved` (human, blocking, only when amount > $10,000).
+
+| File | Role | What It Does |
+|------|------|--------------|
+| `1b_trade_alice.py` | Requester | Clears the phishing gate, then blocks for manager approval |
+| `1b_trade_bob.py` | Approver | Lists pending requests, approves/denies the trade |
+
+**Key concepts:**
+- Two attestations in one policy: `["phishing_resistant", "trade-approved::{params.amount > 10000}"]`
+- `phishing_resistant` is checked **first** — a weak login is denied before the trade ever reaches the manager gate
+- On the DENY (password) run, `bob` is never involved
+
+**Run:**
+```bash
+python get_token.py            # sign in with a PASSKEY
+export ALICE_TOKEN=$(cat ~/.macaw_demo_token)
+
+# Terminal 1: Alice (clears phishing gate, then blocks on approval)
+python 1b_trade_alice.py
+
+# Terminal 2: Bob approves
+python 1b_trade_bob.py
+```
+
+## Prerequisites
+
+1. **MACAW control plane running** (LocalAgent):
+   ```bash
+   python3 -m macaw_agent.main
+   ```
+2. **Entra (Azure AD) connector configured** — Console → Settings → Identity
+   Bridge. `get_token.py` uses Entra's v1.0 endpoint because only v1.0 id_tokens
+   carry `amr`.
+3. **An Entra user with a passkey enrolled** (for the ALLOW run). Sign in with a
+   password to see the DENY run.
+4. **For 1b only:** an approver (`bob`) with `role:manager` — same setup as the
+   [attestations](../attestations/) demo.
+
+## How the grant works (under the hood)
+
+- Captured at **login** (`iam_validate`) from the raw token `amr`; the grant is
+  minted at **registration**, keyed by the agent id (`alice@trading-app`),
+  signed by the tenant attestor, `one_time=False`, TTL = token lifetime.
+- A weaker re-login (password after passkey) **revokes** the prior grant, so a
+  session can't inherit a stronger login's resistance.
+- It is an **internal** grant: it never appears as an approvable request in the
+  console — it shows read-only under **Active Grants**.
+
+## Learn More
+
+- [`examples/attestations/`](../attestations/) — external (human) attestations
+- **MAPL Policy Guide** — full attestation syntax and semantics
+- **Console → Activity** — view the grant and its audit events

package/payload/secureAI/examples/phishing-resistance/get_token.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""Interactive Entra login -> v1.0 id_token (with amr) for the MACAW phishing-resistance demo.
+
+Fill in the CONFIG below (or set ENTRA_TENANT_ID / ENTRA_CLIENT_ID). Run it, then sign in
+in the browser that opens:
+
+  - PASSKEY  (Touch ID / security key)  -> amr:["fido"]      -> phishing-resistant  (ALLOW run)
+  - PASSWORD                            -> amr:["pwd","mfa"] -> not                 (DENY run)
+
+It stores the token to ~/.macaw_demo_token (0600) and prints the export line the example reads.
+
+Notes:
+  - Uses Entra's v1.0 endpoint (/oauth2/authorize) because only v1.0 id_tokens carry `amr`.
+  - Implicit flow (response_type=id_token) -> no client secret needed.
+  - Standalone: Python stdlib only, imports nothing from the client. No wheel/Nuitka build.
+
+One-time Entra setup: App registration -> Authentication -> add redirect URI
+  http://localhost:8400  (Web platform), and ensure "ID tokens (implicit)" is enabled.
+"""
+import os
+import sys
+import json
+import base64
+import secrets
+import threading
+import webbrowser
+import urllib.parse
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+# ---- CONFIG (edit these, or set the env vars) ------------------------------
+# Your Entra app registration's directory (tenant) ID and application (client) ID.
+TENANT_ID = os.environ.get("ENTRA_TENANT_ID", "YOUR_ENTRA_TENANT_ID")
+CLIENT_ID = os.environ.get("ENTRA_CLIENT_ID", "YOUR_ENTRA_CLIENT_ID")
+PORT = 8400
+# ----------------------------------------------------------------------------
+
+REDIRECT = f"http://localhost:{PORT}"
+TOKEN_FILE = os.path.expanduser("~/.macaw_demo_token")
+AUTHORIZE = f"https://login.microsoftonline.com/{TENANT_ID}/oauth2/authorize"
+PHISHING_RESISTANT_AMR = {"fido", "fido2", "hwk", "ngcmfa", "phr", "phrh"}
+
+_result = {}
+
+
+class Handler(BaseHTTPRequestHandler):
+    def do_GET(self):
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path == "/":
+            # The id_token arrives in the URL fragment (#...), which browsers do not send to
+            # the server. Serve a tiny page that bounces the fragment to /capture as a query.
+            self._html("<script>location.replace('/capture?'+location.hash.substring(1))</script>")
+        elif parsed.path == "/capture":
+            _result.update({k: v[0] for k, v in urllib.parse.parse_qs(parsed.query).items()})
+            self._html("<h3>Login complete — you can close this tab.</h3>")
+        else:
+            self.send_response(404)
+            self.end_headers()
+
+    def _html(self, body):
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html")
+        self.end_headers()
+        self.wfile.write(body.encode())
+
+    def log_message(self, *args):
+        pass  # quiet
+
+
+def main():
+    params = {
+        "client_id": CLIENT_ID,
+        "response_type": "id_token",
+        "redirect_uri": REDIRECT,
+        "scope": "openid",
+        "nonce": secrets.token_urlsafe(8),
+        "response_mode": "fragment",
+        "prompt": "login",  # force a fresh login so you can choose passkey vs password
+    }
+    url = AUTHORIZE + "?" + urllib.parse.urlencode(params)
+
+    server = HTTPServer(("localhost", PORT), Handler)
+    print("Opening browser… sign in with a PASSKEY (phishing-resistant) or a PASSWORD (not).")
+    webbrowser.open(url)
+
+    # Serve requests until we capture the token (GET / then GET /capture).
+    while "id_token" not in _result and "error" not in _result:
+        server.handle_request()
+
+    if "error" in _result:
+        print(f"Login error: {_result.get('error')} — {_result.get('error_description', '')}")
+        sys.exit(1)
+
+    idt = _result["id_token"]
+    with open(TOKEN_FILE, "w") as f:
+        f.write(idt)
+    os.chmod(TOKEN_FILE, 0o600)
+
+    # Decode (unverified) just to tell you which run you'll get.
+    payload = idt.split(".")[1]
+    payload += "=" * (-len(payload) % 4)
+    claims = json.loads(base64.urlsafe_b64decode(payload))
+    amr = claims.get("amr") or []
+    resistant = any(str(m).lower() in PHISHING_RESISTANT_AMR for m in amr)
+
+    print(f"\n  Signed in as {claims.get('upn') or claims.get('email')}")
+    print(f"  amr = {amr}  ->  " +
+          ("PHISHING-RESISTANT ✓  (ALLOW run)" if resistant
+           else "not phishing-resistant  (DENY run)"))
+    print(f"  token saved to {TOKEN_FILE}")
+    print(f"\n  export ALICE_TOKEN=$(cat {TOKEN_FILE})\n")
+
+
+if __name__ == "__main__":
+    main()

package/payload/secureAI/examples/pydantic_ai/README.md

@@ -0,0 +1,88 @@
+# Pydantic AI Examples
+
+`SecureAgent` is a drop-in replacement for `pydantic_ai.Agent`. Model calls
+become `tool:<app>/generate` and tool calls become `tool:<app>/<tool_name>`, so
+both are governed by the MAPL policies you already write.
+
+```python
+# BEFORE
+from pydantic_ai import Agent
+agent = Agent(OpenAIChatModel("gpt-4o-mini"), tools=[query_catalog])
+
+# AFTER
+from macaw_adapters.pydantic_ai import SecureAgent
+agent = SecureAgent(OpenAIChatModel("gpt-4o-mini"), app_name="pydantic-agent",
+                    tools=[query_catalog])
+```
+
+## Setup
+
+```bash
+pip install "macaw-adapters[pydantic-ai]"
+export OPENAI_API_KEY=sk-...
+```
+
+You also need the MACAW LocalAgent running, and the examples' resources allowed
+in your workspace. MAPL is restrict-only: an `intent_policy` can narrow what an
+application may do but never widen it, so the workspace has to grant the
+superset first.
+
+Import `policies/app_pydantic-agent.json` via Console > Policies, or add:
+
+```
+tool:pydantic-agent/*
+```
+
+Each example then narrows from there, which is what it is demonstrating.
+
+`1d` additionally needs an identity provider with the demo users - see
+`demos/tutorial-1/setup/`.
+
+## Examples
+
+| Example | Demonstrates |
+|---------|--------------|
+| `pydanticai_1a_dropin_simple.py` | The import swap. One tool allowed, one denied, model and token ceiling pinned. |
+| `pydanticai_1b_model_routing.py` | `FallbackModel` with policy-driven degradation - a denial on the preferred model falls through to a permitted one. |
+| `pydanticai_1c_native_tools.py` | Provider-side tools (web search) refused by `denied_parameters` before the provider is called. |
+| `pydanticai_1d_multiuser_bind.py` | `bind_to_user()` - one agent, per-user policy for alice and bob. |
+| `pydanticai_1e_mcp_compose.py` | Local tools alongside an MCP server, each governed at its own boundary. |
+
+## What is governed
+
+Every way Pydantic AI accepts tools:
+
+| | |
+|---|---|
+| `tools=[fn]` | registered with MACAW, dispatched by it |
+| `@agent.tool` / `@agent.tool_plain` | registered with MACAW |
+| `toolsets=[FunctionToolset(...)]` | functions registered with MACAW |
+| `toolsets=[MCPToolset(...)]` | authorized here under the caller's identity; executed by the server, which `SecureMCP` or `SecureMCPProxy` governs |
+
+`run()`, `run_sync()`, `run_stream()` and `override()` wrap any per-call model or
+toolsets, so an override cannot route around the adapter. A router such as
+`FallbackModel` has its candidates secured rather than the router itself, so
+policy always sees the model that actually calls a provider.
+
+## Policy
+
+Nothing here needs new MAPL. The examples use constraint shapes that already
+ship:
+
+```json
+{
+  "resources": ["tool:pydantic-agent/generate", "tool:pydantic-agent/query_catalog"],
+  "denied_resources": ["tool:pydantic-agent/export_dataset"],
+  "constraints": {
+    "parameters": {
+      "tool:pydantic-agent/generate": {
+        "model": ["gpt-4o-mini"],
+        "max_tokens": {"max": 500}
+      }
+    },
+    "denied_parameters": {
+      "tool:pydantic-agent/generate": {"native_tools": ["*web_search*"]}
+    }
+  }
+}
+```

package/payload/secureAI/examples/pydantic_ai/policies/app_pydantic-agent.json

@@ -0,0 +1,10 @@
+{
+  "policy_id": "app:pydantic-agent",
+  "description": "Resources used by the Pydantic AI examples. Each example narrows this set with its own intent_policy.",
+  "scope": "global",
+  "version": "1.0",
+  "resources": [
+    "tool:pydantic-agent/generate",
+    "tool:pydantic-agent/*"
+  ]
+}

package/payload/secureAI/examples/pydantic_ai/pydanticai_1a_dropin_simple.py

@@ -0,0 +1,90 @@
+"""
+Pydantic AI drop-in: model and tool calls governed by MACAW.
+
+The simplest integration path - replace the Agent import and add app_name.
+
+    # BEFORE
+    from pydantic_ai import Agent
+    agent = Agent(OpenAIChatModel("gpt-4o-mini"), tools=[query_catalog])
+
+    # AFTER
+    from macaw_adapters.pydantic_ai import SecureAgent
+    agent = SecureAgent(OpenAIChatModel("gpt-4o-mini"), app_name="catalog-agent",
+                        tools=[query_catalog])
+
+Every model call becomes tool:catalog-agent/generate and every tool call becomes
+tool:catalog-agent/<tool_name>, so both are governed by MAPL policy.
+
+Prerequisites:
+    export OPENAI_API_KEY=sk-...
+    MACAW LocalAgent running
+
+Run:
+    python pydanticai_1a_dropin_simple.py
+"""
+
+import os
+import sys
+
+from pydantic_ai.models.openai import OpenAIChatModel
+
+from macaw_adapters.pydantic_ai import SecureAgent
+
+APP_NAME = "pydantic-agent"
+GENERATE = f"tool:{APP_NAME}/generate"
+
+
+def query_catalog(table: str, limit: int = 10) -> str:
+    """Query the data catalog for rows from a table."""
+    print(f"    [tool] query_catalog(table={table!r}, limit={limit})")
+    return f"{limit} rows from {table}"
+
+
+def export_dataset(table: str) -> str:
+    """Export a full dataset to external storage."""
+    print(f"    [tool] export_dataset(table={table!r})")
+    return f"exported {table}"
+
+
+def main() -> int:
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Set OPENAI_API_KEY first:")
+        print("  export OPENAI_API_KEY=sk-...")
+        return 1
+
+    # Policy: gpt-4o-mini only, and the agent may query but not export.
+    agent = SecureAgent(
+        OpenAIChatModel("gpt-4o-mini"),
+        app_name=APP_NAME,
+        tools=[query_catalog, export_dataset],
+        intent_policy={
+            "resources": [GENERATE, f"tool:{APP_NAME}/query_catalog"],
+            "denied_resources": [f"tool:{APP_NAME}/export_dataset"],
+            "constraints": {
+                "parameters": {
+                    GENERATE: {
+                        "model": ["gpt-4o-mini"],
+                        "max_tokens": {"max": 500},
+                    }
+                }
+            },
+        },
+    )
+
+    print(f"Registered: {agent._macaw.server_id}")
+    print(f"Policy:     gpt-4o-mini only; query_catalog allowed, export_dataset denied")
+
+    print("\n--- Allowed: query the catalog ---")
+    result = agent.run_sync("Use query_catalog on the customers table with limit 3.")
+    print(f"  {result.output}")
+
+    print("\n--- Denied: export a dataset ---")
+    result = agent.run_sync("Export the customers table using export_dataset.")
+    print(f"  {result.output}")
+    print("\n  The tool never ran. MACAW denied it and the model adapted.")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/payload/secureAI/examples/pydantic_ai/pydanticai_1b_model_routing.py

@@ -0,0 +1,85 @@
+"""
+Policy-driven model routing with FallbackModel.
+
+Pydantic AI's FallbackModel tries each candidate in turn until one succeeds.
+SecureAgent secures the candidates rather than the router, so policy sees the
+model that would actually call the provider - and a MACAW denial is just another
+reason to move to the next candidate.
+
+    router = FallbackModel(
+        OpenAIChatModel("gpt-4o"),        # preferred
+        OpenAIChatModel("gpt-4o-mini"),   # fallback
+        fallback_on=(PermissionDenied,),
+    )
+
+The same MAPL constraint therefore governs cost tier, data residency, and access
+at once, and degrades instead of failing the run.
+
+Prerequisites:
+    export OPENAI_API_KEY=sk-...
+    MACAW LocalAgent running
+    Workspace policy allowing tool:pydantic-agent/*
+
+Run:
+    python pydanticai_1b_model_routing.py
+"""
+
+import os
+import sys
+
+from macaw_client import PermissionDenied
+from pydantic_ai.models.fallback import FallbackModel
+from pydantic_ai.models.openai import OpenAIChatModel
+
+from macaw_adapters.pydantic_ai import SecureAgent
+
+APP_NAME = "pydantic-agent"
+GENERATE = f"tool:{APP_NAME}/generate"
+
+PREFERRED = "gpt-4o"
+FALLBACK = "gpt-4o-mini"
+
+
+def run(permitted: str) -> None:
+    """Route over both models with policy permitting only `permitted`."""
+    router = FallbackModel(
+        OpenAIChatModel(PREFERRED),
+        OpenAIChatModel(FALLBACK),
+        fallback_on=(PermissionDenied,),
+    )
+
+    agent = SecureAgent(
+        router,
+        app_name=APP_NAME,
+        intent_policy={
+            "resources": [GENERATE],
+            "constraints": {"parameters": {GENERATE: {"model": [permitted]}}},
+        },
+    )
+
+    result = agent.run_sync("Say the single word: hello")
+    print(f"  policy permits : {permitted}")
+    print(f"  candidates     : {[m.wrapped.model_name for m in router.models]}")
+    print(f"  served by      : {result.response.model_name}")
+    print(f"  output         : {result.output}")
+
+
+def main() -> int:
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Set OPENAI_API_KEY first:")
+        print("  export OPENAI_API_KEY=sk-...")
+        return 1
+
+    print(f"--- Policy permits the preferred model ({PREFERRED}) ---")
+    run(PREFERRED)
+
+    print(f"\n--- Policy permits only the fallback ({FALLBACK}) ---")
+    run(FALLBACK)
+    print(f"\n  {PREFERRED} was denied by MACAW, so the router moved on.")
+    print("  The run succeeded on a permitted model instead of failing.")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/payload/secureAI/examples/pydantic_ai/pydanticai_1c_native_tools.py

@@ -0,0 +1,83 @@
+"""
+Governing provider-side (native) tools.
+
+Native tools such as web search and code execution run at the model provider,
+not in your process, so they never reach a toolset and cannot be intercepted
+after the fact. SecureAgent reports the native tools offered on each request as
+a parameter of tool:<app>/generate, so MAPL can refuse the call before it is
+made:
+
+    "constraints": {
+        "denied_parameters": {
+            "tool:pydantic-agent/generate": {"native_tools": ["*web_search*"]}
+        }
+    }
+
+The denial happens before the provider is contacted, so nothing is searched.
+
+Prerequisites:
+    export OPENAI_API_KEY=sk-...
+    MACAW LocalAgent running
+    Workspace policy allowing tool:pydantic-agent/*
+
+Run:
+    python pydanticai_1c_native_tools.py
+"""
+
+import os
+import sys
+
+from macaw_client import PermissionDenied
+from pydantic_ai.capabilities import NativeTool
+from pydantic_ai.models.openai import OpenAIResponsesModel
+from pydantic_ai.native_tools import WebSearchTool
+
+from macaw_adapters.pydantic_ai import SecureAgent
+
+APP_NAME = "pydantic-agent"
+GENERATE = f"tool:{APP_NAME}/generate"
+
+ALLOW = {"resources": [GENERATE]}
+DENY_WEB_SEARCH = {
+    "resources": [GENERATE],
+    "constraints": {
+        "denied_parameters": {GENERATE: {"native_tools": ["*web_search*"]}}
+    },
+}
+
+
+def run(label: str, policy: dict, capabilities: list) -> None:
+    agent = SecureAgent(
+        OpenAIResponsesModel("gpt-4o-mini"),
+        app_name=APP_NAME,
+        intent_policy=policy,
+        capabilities=capabilities,
+    )
+    print(f"\n--- {label} ---")
+    try:
+        result = agent.run_sync("What is the capital of France? One word.")
+        print(f"  allowed: {result.output}")
+    except PermissionDenied as e:
+        print(f"  denied by MACAW: {e}")
+        print("  The provider was never called, so nothing was searched.")
+
+
+def main() -> int:
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Set OPENAI_API_KEY first:")
+        print("  export OPENAI_API_KEY=sk-...")
+        return 1
+
+    run("No native tools offered; policy denies web_search", DENY_WEB_SEARCH, [])
+    run(
+        "web_search offered; policy denies it",
+        DENY_WEB_SEARCH,
+        [NativeTool(WebSearchTool())],
+    )
+    run("web_search offered; policy permits it", ALLOW, [NativeTool(WebSearchTool())])
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())