@macaw-ai/client 0.0.0-stage → 0.9.11

package/payload/secureAI/examples/phishing-resistance/1a_login_alice.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""
+1a_login_alice.py - Phishing-Resistance (login-strength gating)
+
+The simplest phishing-resistance example: a tool that only runs if the
+human behind the agent logged in with a phishing-resistant method
+(passkey / hardware key / WebAuthn).
+
+There is no human in the loop and no waiting. When the user authenticates,
+their token carries an `amr` (authentication methods) claim describing how
+they logged in — `fido`/`hwk` for a passkey, `pwd` for a password. The
+control plane reads it at LOGIN and, if the login was phishing-resistant,
+mints an internal `phishing_resistant` grant for the agent. The Policy
+Enforcement Point then allows or denies with no prompt.
+
+Run it TWICE, changing only how you log in (via get_token.py):
+    PASSKEY   -> amr:["fido"]        -> phishing-resistant  -> ALLOWED
+    PASSWORD  -> amr:["pwd","mfa"]   -> not                 -> DENIED
+
+That single variable — the login method — is the whole lesson.
+
+NOTE: no approver is involved here. 1b_trade_alice.py shows the same gate
+used as a precondition in front of a human approval step.
+
+Prerequisites:
+    - MACAW control plane running (LocalAgent)
+    - Entra (Azure AD) connector configured in Console -> Settings -> Identity Bridge
+    - An Entra user with a passkey enrolled (for the ALLOW run)
+    - A token minted by get_token.py (sets ~/.macaw_demo_token / ALICE_TOKEN)
+
+Run:
+    python get_token.py                       # sign in: passkey (ALLOW) or password (DENY)
+    export ALICE_TOKEN=$(cat ~/.macaw_demo_token)
+    python 1a_login_alice.py
+"""
+
+import json
+import os
+
+from macaw_client import MACAWClient
+
+
+# Any amount — there is no threshold here; phishing_resistant is unconditional.
+TRADE_SYMBOL = "AAPL"
+TRADE_AMOUNT = 500
+
+
+def execute_trade_handler(params):
+    """Execute trade - the actual tool implementation."""
+    print(f"\n  [TOOL] execute_trade invoked!")
+    print(f"         - symbol: {params.get('symbol')}")
+    print(f"         - amount: ${params.get('amount'):,}")
+    print(f"         - action: {params.get('action')}")
+    return {
+        "status": "executed",
+        "symbol": params.get("symbol"),
+        "amount": params.get("amount"),
+        "action": params.get("action"),
+        "trade_id": "TRD-00001",
+        "message": f"Successfully {params.get('action')} ${params.get('amount'):,} of {params.get('symbol')}",
+    }
+
+
+def main():
+    print("=" * 60)
+    print("Example 1a: Phishing-Resistance - Login Gating (Alice)")
+    print("=" * 60)
+
+    # Step 1: Create the Trading Service (provides execute_trade)
+    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("  Make sure the control plane is running: python3 -m macaw_agent.main")
+            return 1
+        print(f"  Service ID: {trading_service.agent_id}")
+    except Exception as e:
+        print(f"  ERROR: Failed to create Trading Service: {e}")
+        return 1
+
+    # Step 2: Authenticate as Alice (token from get_token.py)
+    print("\n[Step 2] Authenticating as alice...")
+    #   passkey login  -> amr:fido    -> phishing-resistant  (ALLOW run)
+    #   password login -> amr:pwd/mfa -> not                 (DENY run)
+    jwt_token = os.environ.get("ALICE_TOKEN")
+    if not jwt_token and os.path.exists(os.path.expanduser("~/.macaw_demo_token")):
+        jwt_token = open(os.path.expanduser("~/.macaw_demo_token")).read().strip()
+    if not jwt_token:
+        print("  ERROR: no ALICE_TOKEN — run get_token.py first")
+        trading_service.unregister()
+        return 1
+    print("  Got JWT token")
+
+    # Step 3: Create Alice's user agent — gated ONLY by phishing_resistant
+    print("\n[Step 3] Creating Alice's user agent...")
+    try:
+        alice = MACAWClient(
+            user_name="alice",
+            iam_token=jwt_token,
+            agent_type="user",
+            app_name="trading-app",
+            intent_policy={
+                "resources": ["tool:trading/execute_trade"],
+                # The one and only gate: the human must have logged in with a
+                # phishing-resistant method. Deny-if-absent — no approver, no wait.
+                "attestations": ["phishing_resistant"],
+            },
+        )
+        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: Invoke the gated tool — allowed iff the login was phishing-resistant
+    print("\n[Step 4] Invoking gated tool (no approver, no waiting)...")
+    print("  Gate: attestation 'phishing_resistant' must be present for alice@trading-app")
+    print("-" * 60)
+    try:
+        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("ALLOWED — login was phishing-resistant (amr:fido)")
+        print("=" * 60)
+        print(f"Result: {json.dumps(result, indent=2)}")
+    except Exception as e:
+        error_msg = str(e)
+        if "phishing_resistant" in error_msg or "attestation" in error_msg.lower() or "denied" in error_msg.lower():
+            print("\n" + "=" * 60)
+            print("DENIED — login was NOT phishing-resistant")
+            print("=" * 60)
+            print(f"\nReason: {error_msg}")
+            print("\nRe-run get_token.py and sign in with a PASSKEY to get the ALLOW path.")
+        else:
+            print(f"\n  ERROR: {e}")
+    finally:
+        print("\n[Cleanup] Unregistering agents...")
+        try:
+            alice.unregister()
+            trading_service.unregister()
+        except Exception:
+            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 (add the Entra connector)")
+        elif "Connection refused" in err or "connect" in err.lower():
+            print("ERROR: Cannot connect to MACAW")
+            print("Fix: Ensure the control plane (LocalAgent) is running")
+        else:
+            print(f"ERROR: {e}")
+        print("=" * 60)
+        sys.exit(1)

package/payload/secureAI/examples/phishing-resistance/1b_trade_alice.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""
+1b_trade_alice.py - Phishing-Resistance as a precondition to human approval
+
+This builds on the alice/bob trade example (examples/attestations/) by
+LAYERING two gates on the same trade:
+
+  1. phishing_resistant  - internal, decided at login from the token's amr.
+                           Deny-if-absent, no approver, checked FIRST.
+  2. trade-approved      - external HITL, blocks waiting for a manager (bob),
+                           only required when amount > $10,000.
+
+Two run outcomes, driven only by how Alice logged in (via get_token.py):
+
+  PASSKEY  -> clears phishing_resistant -> BLOCKS on trade-approved
+              -> bob approves (1b_trade_bob.py) -> trade executes.
+  PASSWORD -> DENIED at phishing_resistant. The trade never reaches the
+              manager gate; bob is never involved.
+
+Start simple with 1a_login_alice.py (phishing-resistance alone); this
+example shows how it composes with a human approval step.
+
+NOTE: interactive — the passkey run needs bob to approve. Not for
+automated test harnesses.
+
+Prerequisites:
+    - MACAW control plane running (LocalAgent)
+    - Entra connector configured (Console -> Settings -> Identity Bridge),
+      an Entra user with a passkey, and a token from get_token.py
+    - bob configured as an approver with role:manager (see attestations/ demo)
+
+Run:
+    python get_token.py                       # sign in with a PASSKEY
+    export ALICE_TOKEN=$(cat ~/.macaw_demo_token)
+
+    # Terminal 1: Alice's trade (clears phishing gate, then blocks on approval)
+    python 1b_trade_alice.py
+
+    # Terminal 2: Bob approves
+    python 1b_trade_bob.py
+"""
+
+import json
+import os
+
+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 1b: Phishing-Resistance + Trade Approval (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:
+        # Alice authenticates via Entra. Token is minted by get_token.py:
+        #   passkey login  -> amr:fido    -> phishing-resistant  (ALLOW path)
+        #   password login -> amr:pwd/mfa -> not                 (DENY path)
+        jwt_token = os.environ.get("ALICE_TOKEN")
+        if not jwt_token and os.path.exists(os.path.expanduser("~/.macaw_demo_token")):
+            jwt_token = open(os.path.expanduser("~/.macaw_demo_token")).read().strip()
+        if not jwt_token:
+            print("  ERROR: no ALICE_TOKEN — run get_token.py first")
+            return 1
+        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": [
+                    # Precondition: the human must have logged in with a phishing-resistant
+                    # method (hardware key / passkey). Deny-if-absent, checked before approval.
+                    "phishing_resistant",
+                    "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 1b_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 1b_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/phishing-resistance/1b_trade_bob.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""
+1b_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 (1b_trade_alice.py running)
+
+Run:
+    # Terminal 1: Run Alice's trade request first
+    python 1b_trade_alice.py
+
+    # Terminal 2: Run Bob's approval
+    python 1b_trade_bob.py
+"""
+
+import json
+
+from macaw_client import MACAWClient, RemoteIdentityProvider
+
+
+def main():
+    print("=" * 60)
+    print("Example 1b: 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 1b_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)