@macaw-ai/client 0.0.0-stage → 0.9.11

package/payload/secureAI/demos/tutorial-2-intent/setup/get_alation_user_token.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""
+get_alation_user_token.py -- one-shot Alation USER token via OAuth authorization_code + PKCE.
+
+Runs the interactive (User-Initiated) OAuth flow: opens a browser to Alation's authorize
+endpoint, catches the redirect on a local callback server, and exchanges the code (+ PKCE
+verifier) for an access_token + refresh_token that act AS the logged-in user. Prints an
+`export ALATION_TOKEN=...` line you paste into the proxy env.
+
+Prereqs: an Alation "User-Initiated OAuth Client" (Confidential, PKCE) whose Redirect URI is
+EXACTLY the one below (default http://127.0.0.1:18722/callback).
+
+Env / config:
+    ALATION_BASE_URL        (required)  e.g. https://macaw.mtse.alationcloud.com
+    ALATION_CLIENT_ID       (required)
+    ALATION_CLIENT_SECRET   (required for Confidential clients; omit for Public)
+    ALATION_REDIRECT_URI    (default http://127.0.0.1:18722/callback  -- MUST match the client)
+    ALATION_SCOPE           (optional, space-delimited)
+    ALATION_AUTHORIZE_PATH  (default /oauth/v1/authorize)
+    ALATION_TOKEN_PATH      (default /oauth/v2/token/)
+
+Run:
+    export ALATION_BASE_URL="https://macaw.mtse.alationcloud.com"
+    export ALATION_CLIENT_ID="..."
+    export ALATION_CLIENT_SECRET="..."
+    python get_alation_user_token.py            # opens the browser, then prints the token
+    python get_alation_user_token.py --refresh <REFRESH_TOKEN>   # renew without logging in again
+"""
+
+import base64
+import hashlib
+import http.server
+import json
+import os
+import secrets
+import sys
+import threading
+import urllib.error
+import urllib.parse
+import urllib.request
+import webbrowser
+
+BASE = os.environ.get("ALATION_BASE_URL", "").rstrip("/")
+CLIENT_ID = os.environ.get("ALATION_CLIENT_ID", "")
+CLIENT_SECRET = os.environ.get("ALATION_CLIENT_SECRET", "")
+REDIRECT = os.environ.get("ALATION_REDIRECT_URI", "http://127.0.0.1:18722/callback")
+SCOPE = os.environ.get("ALATION_SCOPE", "")
+AUTHORIZE_PATH = os.environ.get("ALATION_AUTHORIZE_PATH", "/oauth/v1/authorize")
+# authorization_code exchange is on the v1 family (v2/token is client_credentials-only,
+# it returns unsupported_grant_type). Override with ALATION_TOKEN_PATH if your instance differs.
+TOKEN_PATH = os.environ.get("ALATION_TOKEN_PATH", "/oauth/v1/token")
+
+
+def _post_token(data: dict) -> dict:
+    url = BASE + TOKEN_PATH
+    body = urllib.parse.urlencode(data).encode()
+    req = urllib.request.Request(
+        url, data=body,
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+    )
+    try:
+        with urllib.request.urlopen(req) as r:  # noqa: S310 (trusted Alation host)
+            return json.load(r)
+    except urllib.error.HTTPError as e:
+        detail = e.read().decode("utf-8", "replace")
+        sys.exit(
+            f"\nToken exchange FAILED: POST {url} -> HTTP {e.code}\n"
+            f"  response: {detail}\n"
+            f"  hint: if this says unsupported_grant_type / invalid endpoint, set "
+            f"ALATION_TOKEN_PATH=/oauth/v1/token (match the v1 authorize) and re-run "
+            f"(a NEW browser login -- the auth code is single-use)."
+        )
+
+
+def _print_tokens(tok: dict) -> None:
+    at = tok.get("access_token")
+    rt = tok.get("refresh_token")
+    if not at:
+        sys.exit(f"No access_token in response: {tok}")
+    print("\n" + "=" * 64)
+    print("Alation USER access token (acts as the logged-in user):\n")
+    print(f'export ALATION_TOKEN="{at}"')
+    if rt:
+        print(f'\n# refresh token (renew later): {rt}')
+    print("=" * 64)
+
+
+def refresh(refresh_token: str) -> None:
+    data = {"grant_type": "refresh_token", "refresh_token": refresh_token, "client_id": CLIENT_ID}
+    if CLIENT_SECRET:
+        data["client_secret"] = CLIENT_SECRET
+    _print_tokens(_post_token(data))
+
+
+def login() -> None:
+    # PKCE
+    verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode()
+    challenge = base64.urlsafe_b64encode(
+        hashlib.sha256(verifier.encode()).digest()
+    ).rstrip(b"=").decode()
+    state = secrets.token_urlsafe(16)
+
+    q = {
+        "response_type": "code",
+        "client_id": CLIENT_ID,
+        "redirect_uri": REDIRECT,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+        "state": state,
+    }
+    if SCOPE:
+        q["scope"] = SCOPE
+    authorize_url = f"{BASE}{AUTHORIZE_PATH}?{urllib.parse.urlencode(q)}"
+
+    caught = {}
+    parsed = urllib.parse.urlparse(REDIRECT)
+    host, port, path = parsed.hostname, parsed.port or 80, parsed.path
+
+    class Handler(http.server.BaseHTTPRequestHandler):
+        def do_GET(self):
+            u = urllib.parse.urlparse(self.path)
+            if u.path != path:
+                self.send_response(404); self.end_headers(); return
+            params = urllib.parse.parse_qs(u.query)
+            caught["code"] = (params.get("code") or [None])[0]
+            caught["state"] = (params.get("state") or [None])[0]
+            caught["error"] = (params.get("error") or [None])[0]
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html")
+            self.end_headers()
+            self.wfile.write(b"<h3>Alation login complete - you can close this tab.</h3>")
+
+        def log_message(self, *_):  # silence
+            pass
+
+    srv = http.server.HTTPServer((host, port), Handler)
+    threading.Thread(target=srv.handle_request, daemon=True).start()
+
+    print(f"Opening browser for Alation login...\n  {authorize_url}\n", file=sys.stderr)
+    try:
+        webbrowser.open(authorize_url)
+    except Exception:
+        pass
+    print("If no browser opened, paste the URL above into one.", file=sys.stderr)
+
+    # wait for the single callback
+    import time
+    for _ in range(600):  # ~5 min
+        if caught:
+            break
+        time.sleep(0.5)
+    if not caught:
+        sys.exit("Timed out waiting for the OAuth callback.")
+    if caught.get("error"):
+        sys.exit(f"Authorization error: {caught['error']}")
+    if caught.get("state") != state:
+        sys.exit("State mismatch (possible CSRF) -- aborting.")
+    code = caught.get("code")
+    if not code:
+        sys.exit("No authorization code received.")
+
+    data = {
+        "grant_type": "authorization_code",
+        "code": code,
+        "redirect_uri": REDIRECT,
+        "client_id": CLIENT_ID,
+        "code_verifier": verifier,
+    }
+    if CLIENT_SECRET:
+        data["client_secret"] = CLIENT_SECRET
+    _print_tokens(_post_token(data))
+
+
+if __name__ == "__main__":
+    if not BASE or not CLIENT_ID:
+        sys.exit("Set ALATION_BASE_URL and ALATION_CLIENT_ID (see the module docstring).")
+    if len(sys.argv) == 3 and sys.argv[1] == "--refresh":
+        refresh(sys.argv[2])
+    else:
+        login()

package/payload/secureAI/examples/README.md

@@ -0,0 +1,244 @@
+# MACAW Adapter Examples
+
+These examples demonstrate how MACAW adapters add enterprise security controls to AI applications through **drop-in replacements** for popular frameworks.
+
+## Three Classes of Adapters
+
+MACAW provides API-compatible replacements across the AI stack:
+
+| Category | Frameworks | What It Secures |
+|----------|------------|-----------------|
+| **LLM APIs** | OpenAI, Anthropic | Direct LLM calls (chat completions, messages) |
+| **Agentic Frameworks** | MCP (Model Context Protocol) | Tool servers, resources, agent-to-agent calls |
+| **Orchestrators** | LangChain | Agent executors, tool chains, multi-agent workflows |
+
+The adapters are thin wrappers that route requests through MACAW's security layer. Change one import line - your existing code continues to work unchanged, now with enterprise security built in.
+
+## Why MACAW?
+
+Building production AI applications requires more than just API calls. You need:
+
+- **Policy-based access controls** - Who can use which models? What token limits apply? Which tools are allowed?
+- **Identity propagation** - User identity must flow through every layer for per-user policies
+- **Audit trail** - Tamper-proof logs of every AI operation for compliance
+- **Observability** - Trace requests through the AI stack layers
+
+Without MACAW, implementing these controls requires months of custom development, careful security review, and ongoing maintenance across every integration point.
+
+**With MACAW**, you get all of this by changing an import:
+
+```python
+# Without MACAW: Alice can use any model, any tokens, no audit trail
+from openai import OpenAI
+client = OpenAI()
+
+# With MACAW: Alice blocked from GPT-4 by policy, full audit trail
+from macaw_adapters.openai import SecureOpenAI
+client = SecureOpenAI(app_name="my-app")
+```
+
+MACAW deploys cryptographically-secured policy enforcement points at the edge using a zero-trust mesh architecture. Every tool endpoint becomes a PEP, enabling deterministic security controls even for non-deterministic AI systems.
+
+## 30-Second Quick Start
+
+```python
+# Install
+# pip install macaw-adapters[openai]
+
+from macaw_adapters.openai import SecureOpenAI
+
+# Same API as OpenAI - just a different import
+client = SecureOpenAI(app_name="my-app")
+
+response = client.chat.completions.create(
+    model="gpt-4",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+print(response.choices[0].message.content)
+```
+
+That's it. Your OpenAI calls now flow through MACAW's security layer with policy enforcement and audit logging.
+
+## Examples by Framework
+
+### OpenAI (`openai/`)
+
+Drop-in replacement for the OpenAI Python SDK with full API compatibility including streaming.
+
+| Example | Description |
+|---------|-------------|
+| `openai_1a_dropin_simple.py` | Basic drop-in replacement with app-level policy |
+| `openai_1b_multiuser_bind.py` | Per-user policies via `bind_to_user()` pattern |
+| `openai_1b_multiuser_bind_streaming.py` | Same as 1b with streaming responses |
+| `openai_1c_a2a_invoke.py` | Agent-to-agent calls via `invoke_tool()` |
+| `openai_1d_invocation_patterns.py` | Compares both invocation patterns side-by-side |
+
+**Progression**: Start with 1a for single-user apps. Move to 1b when you need different permissions per user (SaaS). Use 1c for agent orchestration systems. See 1d to understand how both patterns achieve the same security guarantees.
+
+### Anthropic (`anthropic/`)
+
+Drop-in replacement for the Anthropic Python SDK with full API compatibility including streaming.
+
+| Example | Description |
+|---------|-------------|
+| `anthropic_1a_dropin_simple.py` | Basic drop-in replacement with app-level policy |
+| `anthropic_1b_multiuser_bind.py` | Per-user policies via `bind_to_user()` pattern |
+| `anthropic_1b_multiuser_bind_streaming.py` | Same as 1b with streaming responses |
+| `anthropic_1c_a2a_invoke.py` | Agent-to-agent calls via `invoke_tool()` |
+
+**Progression**: Same pattern as OpenAI - the adapters provide consistent security semantics across LLM providers.
+
+### MCP (`mcp/`)
+
+Drop-in replacement for MCP (Model Context Protocol) servers and clients. Secures tool invocations, resource access, and agent communication.
+
+| Example | Description |
+|---------|-------------|
+| `securemcp_server.py` | Basic SecureMCP server with tools and resources |
+| `securemcp_calculator.py` | Calculator server with context tracking |
+| `1a_simple_invocation.py` | Client invoking tools on a server |
+| `1b_discovery_and_resources.py` | Discovering servers and accessing resources |
+| `1c_logging_client.py` | Client with logging support |
+| `1d_progress_client.py` | Progress tracking for long operations |
+| `1e_sampling_*.py` | LLM sampling (client + server) |
+| `1f_elicitation_*.py` | User input elicitation (client + server) |
+| `1g_roots_*.py` | Filesystem roots (client + server) |
+
+**Progression**: Start with the server example to create a SecureMCP tool server. Use 1a-1b to understand client patterns. Examples 1c-1g demonstrate advanced MCP features (logging, progress, sampling, elicitation, roots) all flowing through MACAW's security layer.
+
+### LangChain (`langchain/`)
+
+Drop-in replacements for LangChain agent components with MACAW security controls on tool access.
+
+| Example | Description |
+|---------|-------------|
+| `langchain_1a_dropin_simple.py` | Basic agent with security policy |
+| `langchain_1b_multiuser.py` | Per-user agents with different tool permissions |
+| `langchain_1c_orchestration.py` | Multi-agent supervisor pattern |
+| `langchain_1d_llm_openai.py` | Securing LLM calls (OpenAI) |
+| `langchain_1e_llm_anthropic.py` | Securing LLM calls (Anthropic) |
+| `langchain_1f_memory.py` | Memory integration with security |
+
+**Progression**: Start with 1a to add tool access control to a single agent. Use 1b when different users need different tool permissions. Use 1c for multi-agent systems where each agent has isolated permissions.
+
+### External Attestations (`attestations/`)
+
+Human-in-the-loop approval workflows for sensitive operations. Request blocks until a manager/admin approves.
+
+| Example | Description |
+|---------|-------------|
+| `1a_trade_alice.py` | Requester: High-value trade blocks for manager approval |
+| `1a_trade_bob.py` | Approver: Manager approves/denies pending requests |
+| `1b_grant_researcher.py` | Requester: First call blocks, subsequent calls instant |
+| `1b_grant_admin.py` | Approver: Admin grants reusable capability |
+
+**Progression**: Start with 1a to understand one-time approvals (each trade needs fresh approval). Use 1b for capability grants (approve once, use many times within TTL).
+
+**Two-terminal pattern**: Run the requester script first, then run the approver script in another terminal while the requester waits.
+
+### Phishing-Resistance (`phishing-resistance/`)
+
+Login-strength gating. A tool runs only if the human logged in with a phishing-resistant method (passkey / hardware key). Decided by the control plane at login from the token's `amr` — no human in the loop.
+
+| Example | Description |
+|---------|-------------|
+| `1a_login_alice.py` | Alice alone: a `phishing_resistant`-gated tool. Passkey → allowed, password → denied |
+| `1b_trade_alice.py` | Requester: layers `phishing_resistant` in front of the trade approval |
+| `1b_trade_bob.py` | Approver: manager approves the trade (once the phishing gate is cleared) |
+| `get_token.py` | Signs in to Entra and mints an id_token carrying `amr` (passkey vs password) |
+
+**Progression**: Start with 1a for the pure concept (run it twice — passkey vs password). Use 1b to see it composed as a precondition to a human approval (builds on `attestations/`).
+
+## Running the Examples
+
+### Prerequisites
+
+1. **Install the adapters**:
+   ```bash
+   pip install macaw-adapters[all]
+   # Or specific: pip install macaw-adapters[openai,anthropic,langchain,mcp]
+   ```
+
+2. **Set API keys** (for LLM examples):
+   ```bash
+   export OPENAI_API_KEY=sk-...
+   export ANTHROPIC_API_KEY=sk-ant-...
+   ```
+
+3. **MACAW client configured** (`~/.macaw/config.json`)
+
+### Running
+
+```bash
+# OpenAI drop-in example
+python openai/openai_1a_dropin_simple.py
+
+# Anthropic with streaming
+python anthropic/anthropic_1b_multiuser_bind_streaming.py
+
+# MCP server (run first)
+python mcp/securemcp_server.py
+# Then in another terminal:
+python mcp/1a_simple_invocation.py
+
+# LangChain multi-agent
+python langchain/langchain_1c_orchestration.py
+```
+
+## Tutorial
+
+For a complete end-to-end tutorial with policy setup, identity provider configuration, and a realistic multi-user scenario, see:
+
+**[demos/tutorial-1/](../demos/tutorial-1/)** - Role-Based AI Access Control
+
+This tutorial demonstrates a FinTech Corp scenario with hierarchical policies:
+- **alice** (Analyst): GPT-3.5 only, 500 token limit
+- **bob** (Manager): GPT-3.5/4, 2000 token limit
+- **carol** (Admin): All models, 4000 token limit
+
+Includes setup scripts for Keycloak and Auth0 identity providers, complete MAPL policy files, and three demo applications showing different integration patterns.
+
+## Console Dev Hub
+
+Everything in this repository is also available in the MACAW Console's Dev Hub with interactive features:
+
+```
+Console > Dev Hub
+├── Quick Start
+│   └── Download Client SDK (macOS/Linux/Windows, Python 3.9-3.12) and Adapters
+├── Tutorials
+│   └── Role-Based Access Control
+│       ├── Multi-User SaaS Patterns
+│       ├── Agent Orchestration
+│       └── Policy Hierarchies
+├── Examples
+│   ├── OpenAI (drop-in, multi-user, streaming, A2A)
+│   ├── Anthropic (drop-in, multi-user, streaming, A2A)
+│   ├── MCP
+│   │   ├── Simple Invocation
+│   │   ├── Discovery & Resources
+│   │   ├── Logging
+│   │   ├── Progress Tracking
+│   │   ├── Sampling
+│   │   ├── Elicitation
+│   │   └── Roots
+│   └── LangChain
+│       ├── Drop-in Agents
+│       ├── Multi-user Permissions
+│       ├── Agent Orchestration
+│       ├── LLM Wrappers (OpenAI, Anthropic)
+│       └── Memory Integration
+└── Reference
+    ├── MACAW Client SDK
+    ├── Adapter APIs
+    ├── MAPL Policy Language
+    └── Claims Mapping
+```
+
+Access at [console.macawsecurity.ai](https://console.macawsecurity.ai) → Dev Hub tab.
+
+## Learn More
+
+- **Documentation**: [docs.macawsecurity.ai](https://docs.macawsecurity.ai)
+- **Console**: [console.macawsecurity.ai](https://console.macawsecurity.ai)
+- **GitHub**: [github.com/macawsecurity/secureAI](https://github.com/macawsecurity/secureAI)

package/payload/secureAI/examples/anthropic/anthropic_1a_dropin_simple.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""
+anthropic_1a_dropin_simple.py - Drop-in replacement for Anthropic client
+
+The simplest integration path - just replace your import and it works.
+No Identity Provider needed.
+
+Prerequisites:
+    - MACAW SDK installed (pip install macaw-client macaw-adapters)
+    - ANTHROPIC_API_KEY environment variable
+
+Run:
+    export ANTHROPIC_API_KEY=sk-ant-...
+    python anthropic_1a_dropin_simple.py
+"""
+
+import os
+import sys
+
+# BEFORE: from anthropic import Anthropic
+# AFTER:
+from macaw_adapters.anthropic import SecureAnthropic
+
+
+def main():
+    # Check for API key
+    if not os.environ.get("ANTHROPIC_API_KEY"):
+        print("Set ANTHROPIC_API_KEY environment variable")
+        print("  export ANTHROPIC_API_KEY=sk-ant-...")
+        return
+
+    print("=" * 60)
+    print("Example 1a: Drop-in Replacement (Anthropic)")
+    print("=" * 60)
+    print("\nPath: Direct on service (simplest)")
+    print("Use when: Single app, no user distinction, app-level policies")
+
+    # Create SecureAnthropic - just like regular Anthropic client
+    # Add intent_policy to restrict to Haiku only (no Sonnet/Opus)
+    client = SecureAnthropic(
+        app_name="my-simple-app",
+        intent_policy={
+            "constraints": {
+                "parameters": {
+                    "tool:*/generate": {
+                        "model": ["claude-3-haiku-20240307"],  # Only Haiku allowed
+                        "max_tokens": {"max": 200}
+                    }
+                }
+            }
+        }
+    )
+
+    print(f"\nService registered: {client.server_id}")
+    print(f"Mode: {client._mode}")
+    print("Policy: Haiku only, max 200 tokens")
+
+    # Same API as Anthropic - no changes needed
+    print("\n--- Test 1: Allowed model (claude-3-haiku) ---")
+    response = client.messages.create(
+        model="claude-3-haiku-20240307",
+        max_tokens=100,
+        messages=[
+            {"role": "user", "content": "What is compound interest? Answer briefly."}
+        ]
+    )
+
+    print(f"Model: {response.model}")
+    print(f"Response: {response.content[0].text}")
+
+    # Policy enforcement - try a blocked model
+    print("\n--- Test 2: Blocked model (claude-4.5-opus) ---")
+    try:
+        response = client.messages.create(
+            model="claude-opus-4-5-20251101",  # NOT in allowed list!
+            max_tokens=100,
+            messages=[
+                {"role": "user", "content": "What is compound interest?"}
+            ]
+        )
+        print(f"Unexpected success - should have been blocked!")
+        print(f"Response: {response.content[0].text[:100]}...")
+    except Exception as e:
+        print(f"Correctly blocked: {e}")
+
+    print("\n" + "=" * 60)
+    print("Example complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        err = str(e)
+        print("\n" + "=" * 60)
+        if "ANTHROPIC_API_KEY" in err or "api_key" in err.lower():
+            print("ERROR: Anthropic API key not configured")
+            print("Fix: export ANTHROPIC_API_KEY=sk-ant-...")
+        else:
+            print(f"ERROR: {e}")
+        print("=" * 60)
+        sys.exit(1)