@macaw-ai/client 0.0.0-stage → 0.9.11

package/payload/secureAI/examples/attestations/1a_trade_alice.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""
+1a_trade_alice.py - External Attestation Trade Request
+
+Alice wants to execute a high-value trade ($15,000).
+Policy requires manager approval via external attestation for amounts > $10,000.
+
+This demonstrates:
+- Conditional attestations: only required when amount > 10000
+- Blocking flow: request waits for approval
+- Role-based approval: only users with role:manager can approve
+
+NOTE: This example requires interactive approval and is not suitable
+for automated test harnesses.
+
+Prerequisites:
+    - MACAW SDK installed (pip install macaw-client macaw-adapters)
+    - Identity Provider configured (Console -> Settings -> Identity Bridge)
+    - Test users: alice/Alice123!, bob/Bob@123! (bob needs manager role)
+
+Run:
+    # Terminal 1: Run Alice's trade request (will block waiting)
+    python 1a_trade_alice.py
+
+    # Terminal 2: Run Bob's approval
+    python 1a_trade_bob.py
+"""
+
+import json
+
+from macaw_client import MACAWClient, RemoteIdentityProvider
+
+
+# Trade configuration
+TRADE_SYMBOL = "AAPL"
+TRADE_AMOUNT = 15000  # High-value trade requiring approval
+
+
+def execute_trade_handler(params):
+    """Execute trade - the actual tool implementation."""
+    print(f"\n  [TOOL] execute_trade invoked!")
+    print(f"  [TOOL] Received parameters:")
+    print(f"         - symbol: {params.get('symbol')}")
+    print(f"         - amount: ${params.get('amount'):,}")
+    print(f"         - action: {params.get('action')}")
+
+    # Simulate trade execution
+    result = {
+        "status": "executed",
+        "symbol": params.get("symbol"),
+        "amount": params.get("amount"),
+        "action": params.get("action"),
+        "trade_id": "TRD-12345",
+        "message": f"Successfully {params.get('action')} ${params.get('amount'):,} of {params.get('symbol')}"
+    }
+    print(f"  [TOOL] Returning: {result}")
+    return result
+
+
+def main():
+    print("=" * 60)
+    print("Example 1a: External Attestation - Trade Request (Alice)")
+    print("=" * 60)
+
+    # Step 1: Create Trading Service (provides execute_trade tool)
+    print("\n[Step 1] Creating Trading Service...")
+
+    try:
+        trading_service = MACAWClient(
+            app_name="trading",
+            agent_type="service",
+            tools={
+                "tool:trading/execute_trade": {
+                    "handler": execute_trade_handler,
+                    "description": "Execute a stock trade"
+                }
+            }
+        )
+
+        if not trading_service.register():
+            print("  ERROR: Failed to register Trading Service")
+            print("\n  Make sure LocalAgent is running:")
+            print("    python3 -m macaw_agent.main")
+            return 1
+
+        print(f"  Service ID: {trading_service.agent_id}")
+        print(f"  Provides: tool:trading/execute_trade")
+
+    except Exception as e:
+        print(f"  ERROR: Failed to create Trading Service: {e}")
+        return 1
+
+    # Step 2: Authenticate as Alice
+    print("\n[Step 2] Authenticating as alice...")
+    try:
+        jwt_token, _ = RemoteIdentityProvider().login("alice", "Alice123!")
+        print("  Got JWT token")
+    except Exception as e:
+        print(f"  ERROR: Failed to authenticate: {e}")
+        print("\n  Make sure your identity provider is running and alice user exists")
+        trading_service.unregister()
+        return 1
+
+    # Step 3: Create Alice's user agent with attestation policy
+    print("\n[Step 3] Creating Alice's user agent...")
+    try:
+        # MAPL v3 format for attestations:
+        # - "attestations" array: defines WHEN attestation is required
+        # - "constraints.attestations": defines HOW attestation works
+        alice = MACAWClient(
+            user_name="alice",
+            iam_token=jwt_token,
+            agent_type="user",
+            app_name="trading-app",
+            intent_policy={
+                "resources": ["tool:trading/execute_trade"],
+                # Attestation required when amount > 10000
+                "attestations": [
+                    "trade-approved::{params.amount > 10000}"
+                ],
+                # Attestation metadata
+                "constraints": {
+                    "attestations": {
+                        "trade-approved": {
+                            "approval_criteria": "role:manager",
+                            "timeout": 300,       # 5 minutes to approve
+                            "time_to_live": 3600, # Valid for 1 hour after approval
+                            "one_time": True      # Consumed after single use
+                        }
+                    }
+                }
+            }
+        )
+
+        if not alice.register():
+            print("  ERROR: Failed to register Alice's agent")
+            trading_service.unregister()
+            return 1
+
+        print(f"  Agent ID: {alice.agent_id}")
+
+    except Exception as e:
+        print(f"  ERROR: Failed to create Alice's agent: {e}")
+        trading_service.unregister()
+        return 1
+
+    # Step 4: Execute trade (will block waiting for approval)
+    print("\n[Step 4] Executing trade...")
+    print(f"  Symbol: {TRADE_SYMBOL}")
+    print(f"  Amount: ${TRADE_AMOUNT:,}")
+    print(f"\n  Policy check: amount ({TRADE_AMOUNT}) > 10000 -> attestation REQUIRED")
+    print(f"  Attestation: 'trade-approved' requires role:manager")
+    print(f"\n  Creating PENDING attestation and BLOCKING...")
+    print(f"  Bob has 5 minutes (timeout=300s) to approve.")
+    print(f"\n  >>> Run 1a_trade_bob.py in another terminal <<<")
+    print("-" * 60)
+
+    try:
+        # This will block internally while waiting for attestation
+        result = alice.invoke_tool(
+            tool_name="tool:trading/execute_trade",
+            target_agent=trading_service.agent_id,
+            parameters={
+                "symbol": TRADE_SYMBOL,
+                "amount": TRADE_AMOUNT,
+                "action": "buy"
+            }
+        )
+
+        print("\n" + "=" * 60)
+        print("TRADE EXECUTED SUCCESSFULLY!")
+        print("=" * 60)
+        print(f"Result: {json.dumps(result, indent=2)}")
+
+    except Exception as e:
+        error_msg = str(e)
+        if "attestation" in error_msg.lower() or "denied" in error_msg.lower():
+            print("\n" + "=" * 60)
+            print("TRADE BLOCKED - ATTESTATION REQUIRED OR DENIED")
+            print("=" * 60)
+            print(f"\nError: {error_msg}")
+            print(f"\nTo approve, Bob should run:")
+            print(f"  python 1a_trade_bob.py")
+        else:
+            print(f"\n  ERROR: {e}")
+
+    finally:
+        # Cleanup
+        print("\n[Cleanup] Unregistering agents...")
+        try:
+            alice.unregister()
+            trading_service.unregister()
+        except:
+            pass
+
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+    try:
+        sys.exit(main())
+    except Exception as e:
+        err = str(e)
+        print("\n" + "=" * 60)
+        if "Local provider does not support" in err:
+            print("ERROR: Identity Provider not configured")
+            print("Fix: Console -> Settings -> Identity Bridge")
+        elif "Connection refused" in err or "connect" in err.lower():
+            print("ERROR: Cannot connect to MACAW")
+            print("Fix: Ensure LocalAgent is running")
+        else:
+            print(f"ERROR: {e}")
+        print("=" * 60)
+        sys.exit(1)

package/payload/secureAI/examples/attestations/1a_trade_bob.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""
+1a_trade_bob.py - External Attestation Manager Approval
+
+Bob reviews and approves/denies pending attestation requests.
+Alice's trade request is BLOCKING, waiting for Bob's approval.
+
+This demonstrates:
+- list_attestations(): Find pending requests you can approve
+- approve_attestation(): Grant the request
+- deny_attestation(): Reject the request with reason
+
+NOTE: This example requires interactive input and is not suitable
+for automated test harnesses.
+
+Prerequisites:
+    - MACAW SDK installed (pip install macaw-client macaw-adapters)
+    - Identity Provider configured (Console -> Settings -> Identity Bridge)
+    - Test users: alice/Alice123!, bob/Bob@123! (bob needs manager role)
+    - Alice has already requested a trade (1a_trade_alice.py running)
+
+Run:
+    # Terminal 1: Run Alice's trade request first
+    python 1a_trade_alice.py
+
+    # Terminal 2: Run Bob's approval
+    python 1a_trade_bob.py
+"""
+
+import json
+
+from macaw_client import MACAWClient, RemoteIdentityProvider
+
+
+def main():
+    print("=" * 60)
+    print("Example 1a: External Attestation - Manager Approval (Bob)")
+    print("=" * 60)
+
+    # Step 1: Authenticate as Bob
+    print("\n[Step 1] Authenticating as bob...")
+    try:
+        jwt_token, _ = RemoteIdentityProvider().login("bob", "Bob@123!")
+        print("  Got JWT token")
+    except Exception as e:
+        print(f"  ERROR: Failed to authenticate: {e}")
+        print("\n  Make sure your identity provider is running and bob user exists")
+        return 1
+
+    # Step 2: Create Bob's user agent
+    print("\n[Step 2] Creating Bob's user agent...")
+    try:
+        bob = MACAWClient(
+            user_name="bob",
+            iam_token=jwt_token,
+            agent_type="user",
+            app_name="attestation-manager",
+            intent_policy={
+                "resources": ["attestation:*"],
+                "constraints": {
+                    "roles": ["manager"]
+                }
+            }
+        )
+
+        if not bob.register():
+            print("  ERROR: Failed to register Bob's agent")
+            print("\n  Make sure LocalAgent is running:")
+            print("    python3 -m macaw_agent.main")
+            return 1
+
+        print(f"  Agent ID: {bob.agent_id}")
+
+    except Exception as e:
+        print(f"  ERROR: Failed to create Bob's agent: {e}")
+        return 1
+
+    # Step 3: List pending attestations
+    print("\n[Step 3] Listing pending attestations...")
+    try:
+        attestations = bob.list_attestations(status="pending")
+    except Exception as e:
+        print(f"  ERROR: Failed to list attestations: {e}")
+        bob.unregister()
+        return 1
+
+    if not attestations:
+        print("  No pending attestations found.")
+        print("\n  Make sure Alice has requested a trade first:")
+        print("    python 1a_trade_alice.py")
+        bob.unregister()
+        return 0
+
+    print(f"\n  Found {len(attestations)} pending attestation(s):\n")
+
+    for i, att in enumerate(attestations, 1):
+        print(f"  [{i}] Key: {att.get('key')}")
+        print(f"      For Agent: {att.get('for_agent')}")
+        print(f"      Approval Criteria: {att.get('approval_criteria')}")
+        print(f"      One-Time: {att.get('one_time', False)}")
+        if att.get('value'):
+            print(f"      Value: {json.dumps(att.get('value', {}))}")
+        print()
+
+    # Step 4: Approve/Deny attestation(s)
+    print("[Step 4] Process attestations...")
+    print("  Options: [y] Approve  [d] Deny  [s] Skip")
+
+    for i, att in enumerate(attestations, 1):
+        key = att.get('key')
+        for_agent = att.get('for_agent')
+
+        response = input(f"\n  '{key}' for {for_agent}? [y/d/s]: ").strip().lower()
+
+        if response == 'y':
+            print(f"  Approving...")
+            try:
+                if bob.approve_attestation(att, reason="Manager approved"):
+                    print(f"  APPROVED - Alice's request will proceed")
+                else:
+                    print(f"  Failed to approve")
+            except Exception as e:
+                print(f"  ERROR: {e}")
+
+        elif response == 'd':
+            print(f"  Denying...")
+            try:
+                if bob.deny_attestation(att, reason="Manager denied"):
+                    print(f"  DENIED - Alice's request will be rejected")
+                else:
+                    print(f"  Failed to deny")
+            except Exception as e:
+                print(f"  ERROR: {e}")
+
+        else:
+            print(f"  Skipped")
+
+    # Cleanup
+    bob.unregister()
+
+    print("\n" + "=" * 60)
+    print("Done. Alice's request should now proceed (or fail if denied).")
+    print("=" * 60)
+
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+    try:
+        sys.exit(main())
+    except Exception as e:
+        err = str(e)
+        print("\n" + "=" * 60)
+        if "Local provider does not support" in err:
+            print("ERROR: Identity Provider not configured")
+            print("Fix: Console -> Settings -> Identity Bridge")
+        elif "Connection refused" in err or "connect" in err.lower():
+            print("ERROR: Cannot connect to MACAW")
+            print("Fix: Ensure LocalAgent is running")
+        else:
+            print(f"ERROR: {e}")
+        print("=" * 60)
+        sys.exit(1)

package/payload/secureAI/examples/attestations/1b_grant_admin.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""
+1b_grant_admin.py - Reusable Capability Grant (Admin Approval)
+
+Admin approves capability grants for researchers.
+Since one_time=False, this approval is REUSABLE.
+
+This demonstrates:
+- Identifying reusable vs one-time attestations
+- Granting capabilities that persist
+- Future invocations reuse this approval (no blocking)
+
+NOTE: This example requires interactive input and is not suitable
+for automated test harnesses.
+
+Prerequisites:
+    - MACAW SDK installed (pip install macaw-client macaw-adapters)
+    - Identity Provider configured (Console -> Settings -> Identity Bridge)
+    - Test users: alice/Alice123!, bob/Bob@123! (bob needs admin role)
+    - Researcher script already waiting (1b_grant_researcher.py running)
+
+Run:
+    # Terminal 1: Run researcher request first
+    python 1b_grant_researcher.py
+
+    # Terminal 2: Run admin approval
+    python 1b_grant_admin.py
+"""
+
+import json
+
+from macaw_client import MACAWClient, RemoteIdentityProvider
+
+
+def main():
+    print("=" * 60)
+    print("Example 1b: Reusable Capability Grant - Admin")
+    print("=" * 60)
+
+    # Step 1: Authenticate as admin (using bob with admin role)
+    print("\n[Step 1] Authenticating as admin...")
+    try:
+        jwt_token, _ = RemoteIdentityProvider().login("bob", "Bob@123!")
+        print("  Got JWT token")
+    except Exception as e:
+        print(f"  ERROR: Failed to authenticate: {e}")
+        return 1
+
+    # Step 2: Create admin agent
+    print("\n[Step 2] Creating admin agent...")
+    try:
+        admin = MACAWClient(
+            user_name="admin",
+            iam_token=jwt_token,
+            agent_type="user",
+            app_name="admin-console",
+            intent_policy={
+                "resources": ["attestation:*"],
+                "constraints": {
+                    "roles": ["admin"]
+                }
+            }
+        )
+
+        if not admin.register():
+            print("  ERROR: Failed to register admin agent")
+            return 1
+
+        print(f"  Agent ID: {admin.agent_id}")
+
+    except Exception as e:
+        print(f"  ERROR: {e}")
+        return 1
+
+    # Step 3: List pending attestations
+    print("\n[Step 3] Listing pending attestations...")
+    try:
+        attestations = admin.list_attestations(status="pending")
+    except Exception as e:
+        print(f"  ERROR: {e}")
+        admin.unregister()
+        return 1
+
+    if not attestations:
+        print("  No pending attestations found.")
+        print("\n  Make sure the researcher script is running and waiting.")
+        admin.unregister()
+        return 0
+
+    print(f"\n  Found {len(attestations)} pending attestation(s):\n")
+
+    for i, att in enumerate(attestations, 1):
+        one_time = att.get('one_time', True)
+        print(f"  [{i}] Key: {att.get('key')}")
+        print(f"      For Agent: {att.get('for_agent')}")
+        print(f"      Approval Criteria: {att.get('approval_criteria')}")
+        print(f"      One-Time: {one_time}")
+        if not one_time:
+            print(f"      *** REUSABLE CAPABILITY - approval persists! ***")
+        print()
+
+    # Step 4: Approve attestation(s)
+    print("[Step 4] Process attestations...")
+    print("  Options: [y] Approve  [d] Deny  [s] Skip")
+
+    for i, att in enumerate(attestations, 1):
+        key = att.get('key')
+        for_agent = att.get('for_agent')
+        one_time = att.get('one_time', True)
+
+        prompt = f"\n  '{key}' for {for_agent}"
+        if not one_time:
+            prompt += " (REUSABLE)"
+        prompt += "? [y/d/s]: "
+
+        response = input(prompt).strip().lower()
+
+        if response == 'y':
+            print(f"  Approving...")
+            try:
+                if admin.approve_attestation(att, reason="Admin granted capability"):
+                    print(f"  APPROVED")
+                    if not one_time:
+                        print(f"  *** This approval will be REUSED for future invocations ***")
+                else:
+                    print(f"  Failed to approve")
+            except Exception as e:
+                print(f"  ERROR: {e}")
+
+        elif response == 'd':
+            print(f"  Denying...")
+            try:
+                if admin.deny_attestation(att, reason="Admin denied capability"):
+                    print(f"  DENIED")
+                else:
+                    print(f"  Failed to deny")
+            except Exception as e:
+                print(f"  ERROR: {e}")
+
+        else:
+            print(f"  Skipped")
+
+    # Cleanup
+    admin.unregister()
+
+    print("\n" + "=" * 60)
+    print("Done. Researcher should now proceed.")
+    print("Future invocations will reuse this approval (no blocking).")
+    print("=" * 60)
+
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+    try:
+        sys.exit(main())
+    except Exception as e:
+        err = str(e)
+        print("\n" + "=" * 60)
+        if "Local provider does not support" in err:
+            print("ERROR: Identity Provider not configured")
+            print("Fix: Console -> Settings -> Identity Bridge")
+        elif "Connection refused" in err or "connect" in err.lower():
+            print("ERROR: Cannot connect to MACAW")
+            print("Fix: Ensure LocalAgent is running")
+        else:
+            print(f"ERROR: {e}")
+        print("=" * 60)
+        sys.exit(1)