generate_pairing_code.py

#!/usr/bin/env python3
"""
Generate a pairing code for Open Claw Gateway to use with iOSLobster.

Usage:
    python3 generate_pairing_code.py <tailscale-address> [options]

Examples:
    # HTTPS with fingerprint (standard format)
    python3 generate_pairing_code.py 100.64.1.2 --scheme https --fingerprint "SHA256:abc123..."

    # HTTP/WS (simplified format with token)
    python3 generate_pairing_code.py my-gateway.tailscale.ts.net --scheme ws --token "your-pairing-token"

    # HTTPS/WSS (simplified format with token)
    python3 generate_pairing_code.py 100.64.1.2 --scheme wss --token "your-pairing-token"
"""

import json
import base64
import argparse
import secrets
import sys
from urllib.parse import urlparse


def generate_pairing_code(
    endpoint_url: str,
    fingerprint: str = None,
    challenge: str = None,
    token: str = None,
    gateway_name: str = None,
    version: int = 1
) -> str:
    """
    Generate a pairing code in openclaw://pair format.
    
    Args:
        endpoint_url: Full WebSocket URL (e.g., wss://100.64.1.2/ws or ws://gateway/ws)
        fingerprint: SHA256 fingerprint (for HTTPS/WSS standard format)
        challenge: Challenge string (for standard format)
        token: Pairing token (for simplified format - used as both fingerprint and challenge)
        gateway_name: Optional gateway name
        version: Protocol version (default: 1)
    
    Returns:
        Pairing code string in openclaw://pair?data=... format
    """
    # Parse the endpoint URL
    parsed = urlparse(endpoint_url)
    
    # Ensure it's a WebSocket URL
    if parsed.scheme not in ['ws', 'wss']:
        raise ValueError(f"Endpoint must be a WebSocket URL (ws:// or wss://), got: {endpoint_url}")
    
    # Build the endpoint URL
    endpoint = endpoint_url
    
    # Determine format: simplified (token) or standard (fingerprint + challenge)
    if token:
        # Simplified format: token is used as both fingerprint and challenge
        fingerprint = token
        challenge = token
    elif not fingerprint or not challenge:
        raise ValueError("Either provide --token (simplified format) or both --fingerprint and --challenge (standard format)")
    
    # Create the payload
    payload = {
        "endpoint": endpoint,
        "fingerprint": fingerprint,
        "challenge": challenge,
        "version": version
    }
    
    if gateway_name:
        payload["gateway_name"] = gateway_name
    
    # Encode as JSON
    json_data = json.dumps(payload, sort_keys=True, separators=(',', ':'))
    
    # Base64 encode
    base64_data = base64.b64encode(json_data.encode('utf-8')).decode('utf-8')
    
    # Generate the pairing code
    pairing_code = f"openclaw://pair?data={base64_data}"
    
    return pairing_code


def main():
    parser = argparse.ArgumentParser(
        description="Generate a pairing code for Open Claw Gateway",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  # HTTPS with fingerprint (standard format)
  %(prog)s 100.64.1.2 --scheme https --fingerprint "SHA256:abc123..." --challenge "random123"

  # HTTP/WS (simplified format with token)
  %(prog)s my-gateway.tailscale.ts.net --scheme ws --token "your-pairing-token"

  # HTTPS/WSS (simplified format with token)
  %(prog)s 100.64.1.2 --scheme wss --token "your-pairing-token" --name "My Gateway"
        """
    )
    
    parser.add_argument(
        'address',
        help='Tailscale IP address or hostname (e.g., 100.64.1.2 or my-gateway.tailscale.ts.net)'
    )
    
    parser.add_argument(
        '--scheme',
        choices=['ws', 'wss', 'http', 'https'],
        default='wss',
        help='URL scheme (default: wss). For WebSocket, use ws/wss. For HTTP pairing endpoint, use http/https.'
    )
    
    parser.add_argument(
        '--port',
        type=int,
        help='Port number (default: 443 for wss/https, 80 for ws/http)'
    )
    
    parser.add_argument(
        '--path',
        default='/ws',
        help='WebSocket path (default: /ws)'
    )
    
    parser.add_argument(
        '--fingerprint',
        help='SHA256 fingerprint (for standard format). Format: SHA256:... or hex string'
    )
    
    parser.add_argument(
        '--challenge',
        help='Challenge string (for standard format). If not provided and using standard format, a random one will be generated.'
    )
    
    parser.add_argument(
        '--token',
        help='Pairing token (for simplified format). Used as both fingerprint and challenge.'
    )
    
    parser.add_argument(
        '--name',
        dest='gateway_name',
        help='Gateway name (optional)'
    )
    
    parser.add_argument(
        '--version',
        type=int,
        default=1,
        help='Protocol version (default: 1)'
    )
    
    parser.add_argument(
        '--output-json',
        action='store_true',
        help='Output as JSON instead of openclaw:// URL'
    )
    
    args = parser.parse_args()
    
    # Determine port
    if args.port:
        port = args.port
    elif args.scheme in ['wss', 'https']:
        port = 443
    else:
        port = 80
    
    # Build WebSocket URL
    if port in [443, 80] and ((args.scheme == 'wss' and port == 443) or (args.scheme == 'ws' and port == 80)):
        # Omit port for default ports
        endpoint_url = f"{args.scheme}://{args.address}{args.path}"
    else:
        endpoint_url = f"{args.scheme}://{args.address}:{port}{args.path}"
    
    # Generate challenge if needed (standard format without challenge)
    challenge = args.challenge
    if not args.token and not challenge:
        # Generate a random challenge
        challenge = secrets.token_urlsafe(32)
        print(f"Generated random challenge: {challenge}", file=sys.stderr)
    
    try:
        if args.output_json:
            # Output as JSON
            payload = {
                "endpoint": endpoint_url,
                "fingerprint": args.token or args.fingerprint or "",
                "challenge": args.token or challenge or "",
                "version": args.version
            }
            if args.gateway_name:
                payload["gateway_name"] = args.gateway_name
            print(json.dumps(payload, indent=2))
        else:
            # Generate pairing code
            pairing_code = generate_pairing_code(
                endpoint_url=endpoint_url,
                fingerprint=args.fingerprint,
                challenge=challenge,
                token=args.token,
                gateway_name=args.gateway_name,
                version=args.version
            )
            print(pairing_code)
            
            # Also print QR code-friendly format
            print("\n# To generate a QR code, you can use:", file=sys.stderr)
            print(f"# qrencode '{pairing_code}' -o pairing.png", file=sys.stderr)
            print(f"# Or use an online QR code generator with the URL above", file=sys.stderr)
            
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)


if __name__ == '__main__':
    main()