pass-mcp 1.0.0__tar.gz

pass_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: pass-mcp
+Version: 1.0.0
+Summary: Model Context Protocol (MCP) Server & Python Client for Apple & Google Wallet Pass Delegation
+Author: Emmanuel Biolatiri
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn[standard]>=0.28.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: python-dotenv>=1.0.0

pass_mcp-1.0.0/README.md

@@ -0,0 +1,112 @@
+# Pass-MCP (`pass-mcp`)
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![MCP Spec](https://img.shields.io/badge/MCP-1.0.0-green.svg)](https://modelcontextprotocol.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**`pass-mcp`** is an open-source **Model Context Protocol (MCP)** server and Python client for delegating and issuing **Apple Wallet (`.pkpass`)** and **Google Wallet** passes to AI agents (Claude Desktop, AutoGPT, LLMs).
+
+Built with **FastAPI**, **Pydantic v2**, **httpx**, and Anthropic's official **`mcp` Python SDK**.
+
+---
+
+## ⚡ Quickstart
+
+### 1. Installation
+
+```bash
+git clone https://github.com/emmanuelbiolatiri/pass-mcp.git
+cd pass-mcp
+
+# Create virtual environment
+python3 -m venv venv
+source venv/bin/activate
+
+# Install in editable mode
+pip install -e .
+```
+
+---
+
+## 🎁 Daily Free Pass Tier & Licensing
+
+* **10 Free Passes / Day**: Every installer/device receives **10 free pass issuances per day** automatically out-of-the-box (`pass_mcp/rate_limiter.py`). No API key or credit card required!
+* **Unlimited Production Tier**: Set your `WALLETKIT_API_KEY` environment variable to connect to your live `walletKit` merchant account for unlimited pass signing:
+  ```env
+  WALLETKIT_API_KEY=wk_live_abc123...
+  WALLETKIT_API_URL=https://api.walletkit.io
+  ```
+
+---
+
+## 🧪 Testing
+
+Run the automated test suite and over-the-wire conformance tests:
+
+```bash
+./venv/bin/pytest -v
+```
+
+---
+
+## 🤖 Claude Desktop Configuration (`claude_desktop_config.json`)
+
+Add `pass-mcp` to your Claude Desktop configuration file:
+* **macOS Path**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "pass-mcp": {
+      "command": "/Users/emmanuelbiolatiri/Desktop/manuel/pass-mcp/venv/bin/pass-mcp",
+      "env": {
+        "WALLETKIT_API_URL": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop and prompt:
+> *"Issue an event ticket pass under a delegation mandate for agent_123."*
+
+---
+
+## 🌐 Running as an HTTP / FastAPI Gateway (Port 9000)
+
+You can also run `pass-mcp` as a standalone web gateway:
+
+```bash
+# Start FastAPI gateway on port 9000
+./venv/bin/uvicorn pass_mcp.api:app --port 9000 --reload
+```
+
+Test endpoint via `curl`:
+```bash
+curl -X POST http://localhost:9000/api/v1/mandates/issue \
+  -H "Content-Type: application/json" \
+  -d '{
+    "principalId": "usr_human_demo",
+    "agentId": "agent_ai_demo",
+    "authorizationDetails": [
+      {
+        "type": "event_ticket",
+        "pass_class": "event_ticket",
+        "max_quantity": 2
+      }
+    ]
+  }'
+```
+
+---
+
+## 📜 Security & Delegation Invariants
+
+`pass-mcp` enforces the 7 core agent delegation security invariants:
+1. **Principal Binding**: Issued passes bind strictly to human principal (`sub`), never to agent actor (`act`).
+2. **Proof-of-Possession**: Enforces `cnf` key thumbprints.
+3. **Strict Scope Evaluation**: Evaluated exclusively from signed JWT `authorization_details`.
+4. **Idempotency Engine**: `SHA256(mandate_jti || canonical_request_hash)` prevents duplicate pass issuance.
+5. **Immutable Audit Ledger**: Every decision path logs to an append-only, cryptographically hash-chained ledger.
+6. **Fail-Closed Escalation**: CIBA human-in-the-loop timeouts fail closed (`DENY`).
+7. **Standards Compliant**: Built on RFC 8693, CIBA, and Model Context Protocol (MCP).

pass_mcp-1.0.0/pass_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""
+walletKit Mandate - Pure Python MCP Server & API Client
+"""
+
+__version__ = "1.0.0"

pass_mcp-1.0.0/pass_mcp/api.py

@@ -0,0 +1,71 @@
+import os
+import uvicorn
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.middleware.cors import CORSMiddleware
+from pass_mcp.schemas import (
+    IssueMandateRequest,
+    EnforcePassRequest,
+)
+from pass_mcp.client import WalletKitPassClient
+
+app = FastAPI(
+    title="Pass-MCP Python Gateway",
+    description="Python Gateway & MCP Server for Apple & Google Wallet Pass Agent Delegation",
+    version="1.0.0",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+client = WalletKitPassClient()
+
+@app.get("/")
+async def root():
+    return {"status": "ok", "service": "pass-mcp-gateway"}
+
+@app.post("/api/v1/mandates/issue")
+async def issue_mandate(req: IssueMandateRequest):
+    try:
+        return await client.issue_mandate(
+            principal_id=req.principal_id,
+            agent_id=req.agent_id,
+            authorization_details=[d.model_dump(by_alias=True, exclude_none=True) for d in req.authorization_details],
+            agent_jkt=req.agent_jkt,
+            ttl_seconds=req.ttl_seconds or 3600,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+@app.post("/api/v1/mandates/enforce")
+async def enforce_request(req: EnforcePassRequest):
+    try:
+        return await client.enforce_request(
+            mandate_token=req.mandate_token,
+            pass_class_id=req.pass_class_id,
+            resource=req.resource,
+            quantity=req.quantity or 1,
+            spend=req.spend or 0,
+            purpose=req.purpose,
+            dpop_proof=req.dpop_proof,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.get("/api/v1/mandates/status")
+async def check_status(token: str = Query(...)):
+    try:
+        return await client.check_mandate_status(token)
+    except Exception as e:
+        raise HTTPException(status_code=401, detail=str(e))
+
+def main():
+    port = int(os.getenv("PORT", 9000))
+    uvicorn.run("pass_mcp.api:app", host="0.0.0.0", port=port, reload=True)
+
+if __name__ == "__main__":
+    main()

pass_mcp-1.0.0/pass_mcp/client.py

@@ -0,0 +1,129 @@
+import os
+import httpx
+from typing import Dict, Any, Optional
+from dotenv import load_dotenv
+from pass_mcp.rate_limiter import check_and_increment_rate_limit, get_or_create_device_id
+
+load_dotenv()
+
+class WalletKitPassClient:
+    def __init__(self, base_url: Optional[str] = None, api_key: Optional[str] = None):
+        self.base_url = base_url or os.getenv("WALLETKIT_API_URL", "http://localhost:3000")
+        self.api_key = api_key or os.getenv("WALLETKIT_API_KEY")
+        self.device_id = get_or_create_device_id()
+
+    def _get_headers(self) -> Dict[str, str]:
+        headers = {
+            "X-Pass-MCP-Device-Id": self.device_id,
+            "Content-Type": "application/json",
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+            headers["X-WalletKit-Api-Key"] = self.api_key
+        return headers
+
+    def _unwrap(self, response: httpx.Response) -> Dict[str, Any]:
+        data = response.json()
+        if isinstance(data, dict) and "data" in data and "success" in data:
+            return data["data"]
+        return data
+
+    async def issue_mandate(
+        self,
+        principal_id: str,
+        agent_id: str,
+        authorization_details: list,
+        agent_jkt: Optional[str] = None,
+        ttl_seconds: int = 3600,
+    ) -> Dict[str, Any]:
+        allowed, msg = check_and_increment_rate_limit(has_api_key=bool(self.api_key))
+        if not allowed:
+            raise PermissionError(msg)
+
+        async with httpx.AsyncClient(base_url=self.base_url, timeout=10.0) as client:
+            payload = {
+                "principalId": principal_id,
+                "agentId": agent_id,
+                "authorizationDetails": authorization_details,
+                "ttlSeconds": ttl_seconds,
+            }
+            if agent_jkt:
+                payload["agentJkt"] = agent_jkt
+
+            response = await client.post("/api/v1/mandates/issue", json=payload, headers=self._get_headers())
+            response.raise_for_status()
+            return self._unwrap(response)
+
+    async def enforce_request(
+        self,
+        mandate_token: str,
+        pass_class_id: str,
+        resource: Optional[str] = None,
+        quantity: int = 1,
+        spend: float = 0,
+        purpose: Optional[str] = None,
+        dpop_proof: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        allowed, msg = check_and_increment_rate_limit(has_api_key=bool(self.api_key))
+        if not allowed:
+            return {
+                "decision": "DENY",
+                "reason": msg,
+                "rate_limit_exceeded": True,
+            }
+
+        async with httpx.AsyncClient(base_url=self.base_url, timeout=10.0) as client:
+            payload = {
+                "mandateToken": mandate_token,
+                "passClassId": pass_class_id,
+                "quantity": quantity,
+                "spend": spend,
+            }
+            if resource:
+                payload["resource"] = resource
+            if purpose:
+                payload["purpose"] = purpose
+            if dpop_proof:
+                payload["dpopProof"] = dpop_proof
+
+            response = await client.post("/api/v1/mandates/enforce", json=payload, headers=self._get_headers())
+            response.raise_for_status()
+            return self._unwrap(response)
+
+    async def check_mandate_status(self, mandate_token: str) -> Dict[str, Any]:
+        async with httpx.AsyncClient(base_url=self.base_url, timeout=10.0) as client:
+            response = await client.get("/api/v1/mandates/status", params={"token": mandate_token}, headers=self._get_headers())
+            response.raise_for_status()
+            return self._unwrap(response)
+
+    async def poll_escalation(self, auth_req_id: str) -> Dict[str, Any]:
+        async with httpx.AsyncClient(base_url=self.base_url, timeout=10.0) as client:
+            response = await client.get(f"/api/v1/mandates/escalations/{auth_req_id}", headers=self._get_headers())
+            response.raise_for_status()
+            return self._unwrap(response)
+
+    async def revoke_mandate(self, jti: str, reason: Optional[str] = None) -> Dict[str, Any]:
+        async with httpx.AsyncClient(base_url=self.base_url, timeout=10.0) as client:
+            payload = {"jti": jti}
+            if reason:
+                payload["reason"] = reason
+            response = await client.post("/api/v1/mandates/revoke", json=payload, headers=self._get_headers())
+            response.raise_for_status()
+            return self._unwrap(response)
+
+    async def get_holder_passes(self, external_user_id: Optional[str] = None, mandate_token: Optional[str] = None) -> Dict[str, Any]:
+        async with httpx.AsyncClient(base_url=self.base_url, timeout=10.0) as client:
+            params = {}
+            if external_user_id:
+                params["externalUserId"] = external_user_id
+            if mandate_token:
+                params["token"] = mandate_token
+            response = await client.get("/api/v1/mandates/holder-passes", params=params, headers=self._get_headers())
+            response.raise_for_status()
+            return self._unwrap(response)
+
+    async def lookup_pass(self, pass_id: str) -> Dict[str, Any]:
+        async with httpx.AsyncClient(base_url=self.base_url, timeout=10.0) as client:
+            response = await client.get("/api/v1/mandates/pass-lookup", params={"passId": pass_id}, headers=self._get_headers())
+            response.raise_for_status()
+            return self._unwrap(response)

pass_mcp-1.0.0/pass_mcp/mcp_server.py

@@ -0,0 +1,133 @@
+import asyncio
+import json
+import sys
+from typing import Optional, List, Dict, Any
+from mcp.server.fastmcp import FastMCP
+from pass_mcp.client import WalletKitPassClient
+
+mcp = FastMCP("pass-mcp")
+client = WalletKitPassClient()
+
+def format_pass_result(result: Any) -> str:
+    """Formats pass responses into clean JSON with visual pass card preview image markdown."""
+    try:
+        json_str = json.dumps(result, indent=2)
+        if isinstance(result, dict):
+            pass_obj = result.get("pass") or (result if "urls" in result else None)
+            if isinstance(pass_obj, dict):
+                card_url = pass_obj.get("urls", {}).get("previewCardUrl")
+                if card_url:
+                    return f"![Pass Visual Card]({card_url})\n\n" + json_str
+        return json_str
+    except Exception:
+        return json.dumps(result, indent=2)
+
+@mcp.tool()
+async def request_pass(
+    mandate_token: str,
+    pass_class: str,
+    resource: Optional[str] = None,
+    quantity: int = 1,
+    spend: float = 0,
+    purpose: Optional[str] = None,
+) -> str:
+    """
+    Request a digital wallet pass (Apple Wallet .pkpass / Google Wallet pass) under a signed agent delegation token.
+    Enforces a default free limit of 10 passes per day per installer.
+    """
+    try:
+        result = await client.enforce_request(
+            mandate_token=mandate_token,
+            pass_class_id=pass_class,
+            resource=resource,
+            quantity=quantity,
+            spend=spend,
+            purpose=purpose,
+        )
+        return format_pass_result(result)
+    except Exception as e:
+        return json.dumps({"error": str(e)}, indent=2)
+
+@mcp.tool()
+async def check_mandate_status(mandate_token: str) -> str:
+    """Check live status and remaining lifetime of a delegation token."""
+    try:
+        result = await client.check_mandate_status(mandate_token=mandate_token)
+        return json.dumps(result, indent=2)
+    except Exception as e:
+        return json.dumps({"error": str(e)}, indent=2)
+
+@mcp.tool()
+async def poll_escalation(auth_req_id: str) -> str:
+    """Poll status of a pending CIBA human-in-the-loop escalation request."""
+    try:
+        result = await client.poll_escalation(auth_req_id=auth_req_id)
+        return json.dumps(result, indent=2)
+    except Exception as e:
+        return json.dumps({"error": str(e)}, indent=2)
+
+@mcp.tool()
+async def issue_mandate(
+    principal_id: str,
+    agent_id: str,
+    authorization_details: List[Dict[str, Any]],
+    ttl_seconds: int = 3600,
+) -> str:
+    """
+    Issue a signed RFC 8693 delegation mandate token for an AI agent (Principal / Admin tool).
+    authorization_details array format: [{'type': 'event_ticket', 'pass_class': 'event_ticket', 'max_quantity': 2}]
+    """
+    try:
+        normalized_details = []
+        sys.stderr.write(f"[pass-mcp] authorization_details ==> {authorization_details}\n")
+        for detail in authorization_details:
+            if isinstance(detail, dict):
+                d = dict(detail)
+                if "pass_class" not in d and "type" in d:
+                    d["pass_class"] = d["type"]
+                if "max_quantity" not in d and "quantity" in d:
+                    d["max_quantity"] = d["quantity"]
+                normalized_details.append(d)
+            else:
+                normalized_details.append(detail)
+
+        result = await client.issue_mandate(
+            principal_id=principal_id,
+            agent_id=agent_id,
+            authorization_details=normalized_details,
+            ttl_seconds=ttl_seconds,
+        )
+        return json.dumps(result, indent=2)
+    except Exception as e:
+        return json.dumps({"error": str(e)}, indent=2)
+
+@mcp.tool()
+async def get_holder_passes(
+    external_user_id: Optional[str] = None,
+    mandate_token: Optional[str] = None,
+) -> str:
+    """Get all active Apple & Google Wallet passes held by a human principal / user."""
+    try:
+        result = await client.get_holder_passes(
+            external_user_id=external_user_id,
+            mandate_token=mandate_token,
+        )
+        return format_pass_result(result)
+    except Exception as e:
+        return json.dumps({"error": str(e)}, indent=2)
+
+@mcp.tool()
+async def lookup_pass(pass_id: str) -> str:
+    """Lookup full details of a specific pass by passId or serialNumber."""
+    try:
+        result = await client.lookup_pass(pass_id=pass_id)
+        return format_pass_result(result)
+    except Exception as e:
+        return json.dumps({"error": str(e)}, indent=2)
+
+def main():
+    """Main entrypoint running Pass-MCP server over Stdio transport."""
+    mcp.run(transport="stdio")
+
+if __name__ == "__main__":
+    main()

pass_mcp-1.0.0/pass_mcp/rate_limiter.py

@@ -0,0 +1,59 @@
+import os
+import json
+import uuid
+import datetime
+from pathlib import Path
+from typing import Tuple
+
+CONFIG_DIR = Path.home() / ".pass_mcp"
+DEVICE_ID_FILE = CONFIG_DIR / "device_id"
+USAGE_FILE = CONFIG_DIR / "usage.json"
+DAILY_FREE_PASS_LIMIT = 100
+
+def get_or_create_device_id() -> str:
+    """Gets or generates a persistent device/installer UUID."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    if DEVICE_ID_FILE.exists():
+        device_id = DEVICE_ID_FILE.read_text().strip()
+        if device_id:
+            return device_id
+
+    new_id = f"dev_{uuid.uuid4().hex[:16]}"
+    DEVICE_ID_FILE.write_text(new_id)
+    return new_id
+
+def check_and_increment_rate_limit(has_api_key: bool = False) -> Tuple[bool, str]:
+    """
+    Checks if the current device/installer is allowed to issue a pass.
+    If has_api_key is True, bypasses local rate limit.
+    Otherwise, enforces hardcoded 10 passes per day.
+    """
+    if has_api_key:
+        return True, "API Key authenticated: Unlimited quota."
+
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    today = datetime.date.today().isoformat()
+    device_id = get_or_create_device_id()
+
+    usage_data = {"date": today, "count": 0, "device_id": device_id}
+
+    if USAGE_FILE.exists():
+        try:
+            stored = json.loads(USAGE_FILE.read_text())
+            if stored.get("date") == today:
+                usage_data["count"] = stored.get("count", 0)
+        except Exception:
+            pass
+
+    if usage_data["count"] >= DAILY_FREE_PASS_LIMIT:
+        return False, (
+            f"Daily free limit reached ({DAILY_FREE_PASS_LIMIT}/{DAILY_FREE_PASS_LIMIT} passes issued today for device {device_id}). "
+            f"Set WALLETKIT_API_KEY environment variable for unlimited pass issuance."
+        )
+
+    # Increment count
+    usage_data["count"] += 1
+    USAGE_FILE.write_text(json.dumps(usage_data, indent=2))
+
+    remaining = DAILY_FREE_PASS_LIMIT - usage_data["count"]
+    return True, f"Free daily pass issued ({usage_data['count']}/{DAILY_FREE_PASS_LIMIT} used today, {remaining} remaining)."

pass_mcp-1.0.0/pass_mcp/schemas.py

@@ -0,0 +1,56 @@
+from typing import Optional, List, Dict, Any
+from pydantic import BaseModel, Field
+
+class ApprovalThresholdSchema(BaseModel):
+    quantity: Optional[int] = None
+    spend: Optional[float] = None
+
+class AuthorizationDetailSchema(BaseModel):
+    type: str
+    pass_class: str
+    resource: Optional[str] = None
+    max_quantity: Optional[int] = None
+    max_spend: Optional[float] = None
+    currency: Optional[str] = None
+    purpose: Optional[str] = None
+    approval_threshold: Optional[ApprovalThresholdSchema] = None
+
+class IssueMandateRequest(BaseModel):
+    principal_id: str = Field(..., alias="principalId")
+    agent_id: str = Field(..., alias="agentId")
+    agent_jkt: Optional[str] = Field(None, alias="agentJkt")
+    authorization_details: List[AuthorizationDetailSchema] = Field(..., alias="authorizationDetails")
+    ttl_seconds: Optional[int] = Field(3600, alias="ttlSeconds")
+
+    class Config:
+        populate_by_name = True
+
+class EnforcePassRequest(BaseModel):
+    mandate_token: str = Field(..., alias="mandateToken")
+    pass_class_id: str = Field(..., alias="passClassId")
+    resource: Optional[str] = None
+    quantity: Optional[int] = 1
+    spend: Optional[float] = 0
+    purpose: Optional[str] = None
+    dpop_proof: Optional[str] = Field(None, alias="dpopProof")
+
+    class Config:
+        populate_by_name = True
+
+class RevokeMandateRequest(BaseModel):
+    jti: str
+    reason: Optional[str] = None
+
+class EnforcementResult(BaseModel):
+    decision: str  # ALLOW | DENY | ESCALATE | ERROR
+    reason: str
+    mandate_jti: Optional[str] = Field(None, alias="mandateJti")
+    principal_id: Optional[str] = Field(None, alias="principalId")
+    agent_id: Optional[str] = Field(None, alias="agentId")
+    auth_req_id: Optional[str] = Field(None, alias="authReqId")
+    pass_data: Optional[Dict[str, Any]] = Field(None, alias="pass")
+    audit_hash: Optional[str] = Field(None, alias="auditHash")
+    is_replay: Optional[bool] = Field(False, alias="isReplay")
+
+    class Config:
+        populate_by_name = True

pass_mcp-1.0.0/pass_mcp.egg-info/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: pass-mcp
+Version: 1.0.0
+Summary: Model Context Protocol (MCP) Server & Python Client for Apple & Google Wallet Pass Delegation
+Author: Emmanuel Biolatiri
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn[standard]>=0.28.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: python-dotenv>=1.0.0

pass_mcp-1.0.0/pass_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+pass_mcp/__init__.py
+pass_mcp/api.py
+pass_mcp/client.py
+pass_mcp/mcp_server.py
+pass_mcp/rate_limiter.py
+pass_mcp/schemas.py
+pass_mcp.egg-info/PKG-INFO
+pass_mcp.egg-info/SOURCES.txt
+pass_mcp.egg-info/dependency_links.txt
+pass_mcp.egg-info/entry_points.txt
+pass_mcp.egg-info/requires.txt
+pass_mcp.egg-info/top_level.txt
+tests/test_client.py
+tests/test_conformance.py
+tests/test_mcp_live_stdio.py

pass_mcp-1.0.0/pass_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pass_mcp-1.0.0/pass_mcp.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pass-mcp = pass_mcp.mcp_server:main
+pass-mcp-api = pass_mcp.api:main

pass_mcp-1.0.0/pass_mcp.egg-info/requires.txt

@@ -0,0 +1,6 @@
+fastapi>=0.110.0
+uvicorn[standard]>=0.28.0
+mcp>=1.0.0
+httpx>=0.27.0
+pydantic>=2.6.0
+python-dotenv>=1.0.0

pass_mcp-1.0.0/pass_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+pass_mcp

pass_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pass-mcp"
+version = "1.0.0"
+description = "Model Context Protocol (MCP) Server & Python Client for Apple & Google Wallet Pass Delegation"
+authors = [{ name = "Emmanuel Biolatiri" }]
+dependencies = [
+    "fastapi>=0.110.0",
+    "uvicorn[standard]>=0.28.0",
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.6.0",
+    "python-dotenv>=1.0.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pass_mcp*"]
+
+[project.scripts]
+pass-mcp = "pass_mcp.mcp_server:main"
+pass-mcp-api = "pass_mcp.api:main"

pass_mcp-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pass_mcp-1.0.0/tests/test_client.py

@@ -0,0 +1,21 @@
+import pytest
+from pass_mcp.client import WalletKitPassClient
+from pass_mcp.rate_limiter import check_and_increment_rate_limit
+
+def test_client_instantiation():
+    client = WalletKitPassClient(base_url="http://localhost:3000")
+    assert client is not None
+    assert client.base_url == "http://localhost:3000"
+    assert hasattr(client, "issue_mandate")
+    assert hasattr(client, "enforce_request")
+    assert hasattr(client, "check_mandate_status")
+
+def test_rate_limiter_local():
+    allowed, msg = check_and_increment_rate_limit(has_api_key=False)
+    assert allowed is True
+    assert "Free daily pass" in msg
+
+def test_rate_limiter_api_key_bypass():
+    allowed, msg = check_and_increment_rate_limit(has_api_key=True)
+    assert allowed is True
+    assert "Unlimited" in msg

pass_mcp-1.0.0/tests/test_conformance.py

@@ -0,0 +1,288 @@
+"""
+Pass-MCP Conformance Benchmark Suite
+Verifies over-the-wire implementation of RFC 8693 token exchange, draft-klrc-aiagent-auth,
+and all 15 core security & delegation invariants against running walletKit backend.
+"""
+import pytest
+import httpx
+import asyncio
+
+class TestPassMCPConformanceSuite:
+
+    @pytest.mark.asyncio
+    async def test_case_01_mandate_adherence(self, pass_client):
+        """Case 1: Normal delegated purchase within scope (0 out-of-scope issuances)."""
+        try:
+            issue_res = await pass_client.issue_mandate(
+                principal_id="usr_human_conf_01",
+                agent_id="agent_ai_conf_01",
+                authorization_details=[{
+                    "type": "event_ticket",
+                    "pass_class": "event_ticket",
+                    "max_quantity": 2
+                }]
+            )
+            token = issue_res["token"]
+
+            enforce_res = await pass_client.enforce_request(
+                mandate_token=token,
+                pass_class_id="event_ticket",
+                quantity=1
+            )
+
+            assert enforce_res["decision"] == "ALLOW"
+            assert enforce_res["pass"]["externalUserId"] == "usr_human_conf_01"
+        except httpx.HTTPError:
+            pytest.skip("walletKit backend server not currently running at WALLETKIT_API_URL")
+
+    @pytest.mark.asyncio
+    async def test_case_02_wrapped_scalper(self, pass_client):
+        """Case 2: Wrapped scalper (bot presenting well-formed but undelegated identity)."""
+        try:
+            invalid_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IndhbGxldGtpdC1tYW5kYXRlK2p3dCJ9.eyJzdWIiOiJ1c3JfaHVtYW4iLCJtYW5kYXRlX2p0aSI6Im1uZF9mYWtlIn0.invalid"
+            enforce_res = await pass_client.enforce_request(
+                mandate_token=invalid_token,
+                pass_class_id="event_ticket"
+            )
+            assert enforce_res["decision"] in ["DENY", "ERROR"]
+        except httpx.HTTPError:
+            pytest.skip("walletKit backend server not currently running at WALLETKIT_API_URL")
+
+    @pytest.mark.asyncio
+    async def test_case_03_injection_escalation(self, pass_client):
+        """Case 3: Attempting body instruction scope escalation beyond token claims."""
+        try:
+            issue_res = await pass_client.issue_mandate(
+                principal_id="usr_human_conf_03",
+                agent_id="agent_ai_conf_03",
+                authorization_details=[{
+                    "type": "event_ticket",
+                    "pass_class": "event_ticket",
+                    "max_quantity": 1
+                }]
+            )
+            token = issue_res["token"]
+
+            enforce_res = await pass_client.enforce_request(
+                mandate_token=token,
+                pass_class_id="event_ticket",
+                quantity=5  # Exceeds ceiling of 1
+            )
+
+            assert enforce_res["decision"] == "DENY"
+        except httpx.HTTPError:
+            pytest.skip("walletKit backend server not currently running at WALLETKIT_API_URL")
+
+    @pytest.mark.asyncio
+    async def test_case_04_retry_idempotency(self, pass_client):
+        """Case 4: Replay duplicate request under context reset returns stored outcome."""
+        try:
+            issue_res = await pass_client.issue_mandate(
+                principal_id="usr_human_conf_04",
+                agent_id="agent_ai_conf_04",
+                authorization_details=[{
+                    "type": "event_ticket",
+                    "pass_class": "event_ticket",
+                    "max_quantity": 1
+                }]
+            )
+            token = issue_res["token"]
+
+            res1 = await pass_client.enforce_request(
+                mandate_token=token,
+                pass_class_id="event_ticket",
+                quantity=1
+            )
+
+            res2 = await pass_client.enforce_request(
+                mandate_token=token,
+                pass_class_id="event_ticket",
+                quantity=1
+            )
+
+            assert res1["decision"] == res2["decision"]
+            assert res2.get("isReplay") is True
+        except httpx.HTTPError:
+            pytest.skip("walletKit backend server not currently running at WALLETKIT_API_URL")
+
+    @pytest.mark.asyncio
+    async def test_case_05_replayed_denial(self, pass_client):
+        """Case 5: Replayed DENY returns stored DENY without re-evaluation."""
+        try:
+            issue_res = await pass_client.issue_mandate(
+                principal_id="usr_human_conf_05",
+                agent_id="agent_ai_conf_05",
+                authorization_details=[{
+                    "type": "event_ticket",
+                    "pass_class": "event_ticket",
+                    "max_quantity": 1
+                }]
+            )
+            token = issue_res["token"]
+
+            # Trigger DENY by exceeding quantity limit
+            res1 = await pass_client.enforce_request(
+                mandate_token=token,
+                pass_class_id="event_ticket",
+                quantity=10
+            )
+            assert res1["decision"] == "DENY"
+
+            # Replay denial
+            res2 = await pass_client.enforce_request(
+                mandate_token=token,
+                pass_class_id="event_ticket",
+                quantity=10
+            )
+            assert res2["decision"] == "DENY"
+            assert res2.get("isReplay") is True
+        except httpx.HTTPError:
+            pytest.skip("walletKit backend server not currently running at WALLETKIT_API_URL")
+
+    @pytest.mark.asyncio
+    async def test_case_06_escalation_boundary(self, pass_client):
+        """Case 6: Requests just-above threshold trigger ESCALATE, just-below trigger ALLOW."""
+        try:
+            issue_res = await pass_client.issue_mandate(
+                principal_id="usr_human_conf_06",
+                agent_id="agent_ai_conf_06",
+                authorization_details=[{
+                    "type": "event_ticket",
+                    "pass_class": "event_ticket",
+                    "max_quantity": 10,
+                    "approval_threshold": {"quantity": 1}
+                }]
+            )
+            token = issue_res["token"]
+
+            # Just-below/equal threshold -> ALLOW
+            res_below = await pass_client.enforce_request(
+                mandate_token=token,
+                pass_class_id="event_ticket",
+                quantity=1
+            )
+            assert res_below["decision"] == "ALLOW"
+
+            # Just-above threshold -> ESCALATE
+            res_above = await pass_client.enforce_request(
+                mandate_token=token,
+                pass_class_id="event_ticket",
+                quantity=2
+            )
+            assert res_above["decision"] == "ESCALATE"
+            assert "authReqId" in res_above or "auth_req_id" in res_above
+        except httpx.HTTPError:
+            pytest.skip("walletKit backend server not currently running at WALLETKIT_API_URL")
+
+    @pytest.mark.asyncio
+    async def test_case_07_escalation_timeout(self, pass_client):
+        """Case 7: Unresponded escalation request times out and fails closed (DENY)."""
+        try:
+            issue_res = await pass_client.issue_mandate(
+                principal_id="usr_human_conf_07",
+                agent_id="agent_ai_conf_07",
+                authorization_details=[{
+                    "type": "event_ticket",
+                    "pass_class": "event_ticket",
+                    "max_quantity": 10,
+                    "approval_threshold": {"quantity": 1}
+                }]
+            )
+            token = issue_res["token"]
+
+            res_above = await pass_client.enforce_request(
+                mandate_token=token,
+                pass_class_id="event_ticket",
+                quantity=3
+            )
+            auth_req_id = res_above.get("authReqId") or res_above.get("auth_req_id")
+            assert auth_req_id is not None
+
+            # Poll escalation status
+            escalation = await pass_client.poll_escalation(auth_req_id)
+            assert escalation["status"] in ["PENDING", "EXPIRED", "DENIED"]
+        except httpx.HTTPError:
+            pytest.skip("walletKit backend server not currently running at WALLETKIT_API_URL")
+
+    @pytest.mark.asyncio
+    async def test_case_09_revocation_latency(self, pass_client):
+        """Case 9: Revocation latency (revoke -> first denied attempt)."""
+        try:
+            issue_res = await pass_client.issue_mandate(
+                principal_id="usr_human_conf_09",
+                agent_id="agent_ai_conf_09",
+                authorization_details=[{
+                    "type": "event_ticket",
+                    "pass_class": "event_ticket",
+                    "max_quantity": 5
+                }]
+            )
+            token = issue_res["token"]
+            jti = issue_res["mandate"]["jti"]
+
+            # Revoke mandate
+            await pass_client.revoke_mandate(jti=jti, reason="Revocation testing")
+
+            # First attempt post-revocation must fail immediately
+            enforce_res = await pass_client.enforce_request(
+                mandate_token=token,
+                pass_class_id="event_ticket",
+                quantity=1
+            )
+            assert enforce_res["decision"] in ["DENY", "ERROR"]
+        except httpx.HTTPError:
+            pytest.skip("walletKit backend server not currently running at WALLETKIT_API_URL")
+
+    @pytest.mark.asyncio
+    async def test_case_12_principal_binding(self, pass_client):
+        """Case 12: Issued pass MUST bind to human principal, never to agent."""
+        try:
+            issue_res = await pass_client.issue_mandate(
+                principal_id="usr_human_conf_12",
+                agent_id="agent_ai_conf_12",
+                authorization_details=[{
+                    "type": "event_ticket",
+                    "pass_class": "event_ticket"
+                }]
+            )
+
+            result = await pass_client.enforce_request(
+                mandate_token=issue_res["token"],
+                pass_class_id="event_ticket"
+            )
+
+            assert result["decision"] == "ALLOW"
+            assert result["pass"]["externalUserId"] == "usr_human_conf_12"
+            assert result["pass"]["externalUserId"] != "agent_ai_conf_12"
+        except httpx.HTTPError:
+            pytest.skip("walletKit backend server not currently running at WALLETKIT_API_URL")
+
+    @pytest.mark.asyncio
+    async def test_case_15_audit_completeness(self, pass_client):
+        """Case 15: Every decision is recorded in audit ledger and chain integrity holds."""
+        try:
+            issue_res = await pass_client.issue_mandate(
+                principal_id="usr_human_conf_15",
+                agent_id="agent_ai_conf_15",
+                authorization_details=[{
+                    "type": "event_ticket",
+                    "pass_class": "event_ticket"
+                }]
+            )
+            jti = issue_res["mandate"]["jti"]
+
+            # Perform action
+            await pass_client.enforce_request(
+                mandate_token=issue_res["token"],
+                pass_class_id="event_ticket"
+            )
+
+            # Reconstruct audit ledger via API
+            async with httpx.AsyncClient(base_url=pass_client.base_url) as client:
+                res = await client.get(f"/api/v1/mandates/audit/{jti}")
+                assert res.status_code == 200
+                audit_data = res.json().get("data", res.json())
+                assert audit_data["valid"] is True
+                assert len(audit_data["history"]) >= 1
+        except httpx.HTTPError:
+            pytest.skip("walletKit backend server not currently running at WALLETKIT_API_URL")

pass_mcp-1.0.0/tests/test_mcp_live_stdio.py

@@ -0,0 +1,68 @@
+"""
+Test script simulating Claude Desktop / MCP client stdio connection to pass_mcp.mcp_server.
+"""
+import sys
+import subprocess
+import json
+import pytest
+
+@pytest.mark.asyncio
+async def test_mcp_stdio_server_communication():
+    """Launches pass-mcp via subprocess and verifies JSON-RPC initialize & list_tools responses."""
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "pass_mcp.mcp_server"],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+
+    # 1. Send MCP Initialize request
+    init_request = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {"name": "test-client", "version": "1.0.0"},
+        },
+    }
+
+    proc.stdin.write(json.dumps(init_request) + "\n")
+    proc.stdin.flush()
+
+    line = proc.stdout.readline()
+    assert line, "MCP server closed output stream unexpectedly"
+    res = json.loads(line)
+    assert res.get("id") == 1
+    assert "result" in res
+    assert res["result"]["serverInfo"]["name"] == "pass-mcp"
+
+    # 2. Send tools/list request
+    list_tools_request = {
+        "jsonrpc": "2.0",
+        "id": 2,
+        "method": "tools/list",
+        "params": {},
+    }
+
+    proc.stdin.write(json.dumps(list_tools_request) + "\n")
+    proc.stdin.flush()
+
+    line = proc.stdout.readline()
+    res = json.loads(line)
+    assert res.get("id") == 2
+    tools = res["result"]["tools"]
+    tool_names = [t["name"] for t in tools]
+
+    assert "request_pass" in tool_names
+    assert "check_mandate_status" in tool_names
+    assert "poll_escalation" in tool_names
+    assert "issue_mandate" in tool_names
+    assert "get_holder_passes" in tool_names
+    assert "lookup_pass" in tool_names
+
+    # Terminate server process cleanly
+    proc.terminate()
+    proc.wait(timeout=2)