Magic Cookies¶

Lightweight plugin authentication using cryptographically secure random tokens, providing strong security for local process communication without certificate overhead.

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

Overview¶

Magic cookies are secure random tokens that authenticate plugin connections. They offer a simpler alternative to certificates while maintaining robust security for process-to-process communication.

Key Benefits¶

Lightweight Security: No PKI infrastructure required
Fast Authentication: Minimal overhead compared to certificates
Process Isolation: Each plugin gets unique authentication tokens
Automatic Generation: Cryptographically secure random generation
Environment Integration: Seamless integration with configuration management

Quick Start¶

from pyvider.rpcplugin import plugin_server, plugin_client
from pyvider.rpcplugin.security import MagicCookie

async def magic_cookie_example():
    """Basic magic cookie authentication."""

    # Generate secure magic cookie
    cookie = MagicCookie.generate()

    # Server with authentication
    server = plugin_server(
        services=[MyService()],
        magic_cookie=cookie.value,
        require_magic_cookie=True
    )

    # Client with matching cookie
    async with plugin_client(
        command=["python", "plugin.py"],
        magic_cookie=cookie.value
    ) as client:
        result = await client.service.secure_method()
        print(f"✅ Authenticated: {result}")

Core Concepts¶

Magic cookies are generated using cryptographically secure random number generators with sufficient entropy to prevent prediction or brute force attacks.

from pyvider.rpcplugin.security import MagicCookie

# Standard generation (256 bits of entropy)
cookie = MagicCookie.generate()

# Custom length
cookie = MagicCookie.generate(length=64)  # 512 bits

# From environment 
cookie = MagicCookie.from_env("PLUGIN_MAGIC_COOKIE")

2. Server Authentication¶

Servers validate magic cookies on every connection attempt, rejecting unauthorized clients immediately.

server = plugin_server(
    services=[MyService()],
    magic_cookie=cookie.value,
    require_magic_cookie=True,        # Reject without cookie
    cookie_timeout=300                # Cookie expires after 5 minutes
)

3. Client Authentication¶

Clients must provide the correct magic cookie to establish connections.

async with plugin_client(
    command=["python", "plugin.py"],
    magic_cookie=cookie.value,
    cookie_validation=True            # Validate cookie format
) as client:
    # All requests authenticated with cookie
    await client.service.protected_method()

Authentication Patterns¶

Development Environment¶

# Fixed cookie for development
cookie = MagicCookie.from_string("dev-magic-cookie-12345")

server = plugin_server(
    magic_cookie=cookie.value,
    require_magic_cookie=False,       # Optional in dev
    cookie_timeout=3600               # 1 hour timeout
)

Production Environment¶

# Generated cookie with strict validation
cookie = MagicCookie.generate(length=64)

server = plugin_server(
    magic_cookie=cookie.value,
    require_magic_cookie=True,        # Always required
    cookie_timeout=300,               # 5 minute timeout
    validate_cookie_entropy=True      # Ensure sufficient randomness
)

Multi-Plugin Environment¶

# Each plugin gets unique cookie
plugin_cookies = {
    "data-processor": MagicCookie.generate(),
    "file-handler": MagicCookie.generate(), 
    "notification-service": MagicCookie.generate()
}

# Start servers with different cookies
for plugin_name, cookie in plugin_cookies.items():
    server = plugin_server(
        services=[get_plugin_service(plugin_name)],
        magic_cookie=cookie.value,
        plugin_id=plugin_name
    )

Configuration Management¶

Environment Variables¶

# Single plugin
export PLUGIN_MAGIC_COOKIE="$(python -c 'from pyvider.rpcplugin.security import MagicCookie; print(MagicCookie.generate().value)')"

# Multiple plugins  
export PLUGIN_DATA_MAGIC_COOKIE="<generated-cookie-1>"
export PLUGIN_FILE_MAGIC_COOKIE="<generated-cookie-2>"
export PLUGIN_NOTIFY_MAGIC_COOKIE="<generated-cookie-3>"

Configuration Files¶

# config.yaml
plugins:
  data_processor:
    magic_cookie: "${PLUGIN_DATA_MAGIC_COOKIE}"
    require_cookie: true
    timeout: 300

  file_handler:
    magic_cookie: "${PLUGIN_FILE_MAGIC_COOKIE}"  
    require_cookie: true
    timeout: 600

Programmatic Configuration¶

from provide.foundation import config

# Load from configuration
plugin_config = config.get_config()
cookie = MagicCookie.from_config(
    plugin_config.magic_cookie,
    fallback_generate=True  # Generate if not configured
)

Error Handling¶

from pyvider.rpcplugin.exception import AuthenticationError, MagicCookieError

async def secure_plugin_connection():
    try:
        async with plugin_client(magic_cookie=cookie.value) as client:
            return await client.service.protected_method()

    except AuthenticationError as e:
        logger.error(f"Authentication failed: {e}")
        # Handle invalid/missing cookie

    except MagicCookieError as e:
        logger.error(f"Cookie error: {e}")
        # Handle malformed cookie

    except TimeoutError:
        logger.error("Cookie validation timed out")
        # Handle timeout scenarios

Security Considerations¶

Generate Fresh: Use new cookies for each session
Sufficient Entropy: Minimum 256 bits of randomness
Secure Storage: Protect cookies like passwords
Limited Lifetime: Set reasonable expiration times
No Logging: Never log cookie values

Transport Security¶

Local Only: Magic cookies designed for local IPC
Process Isolation: Each plugin process gets unique cookies
Memory Protection: Clear cookies from memory after use
Environment Cleanup: Remove cookie environment variables

Best Practices¶

Rotate Regularly: Generate new cookies periodically
Validate Format: Check cookie format and entropy
Monitor Usage: Log authentication attempts and failures
Timeout Appropriately: Balance security with usability
Combine with mTLS: Use both for network communication
Test Authentication: Verify authentication works correctly

Troubleshooting¶

Common Issues¶

Authentication Failures¶

# Check cookie format
if not cookie.is_valid_format():
    logger.error("Invalid cookie format")

# Verify cookie matches
if server_cookie.value != client_cookie.value:
    logger.error("Cookie mismatch")

Environment Problems¶

# Verify cookie is set
echo $PLUGIN_MAGIC_COOKIE

# Check cookie length
python -c "import os; print(len(os.environ.get('PLUGIN_MAGIC_COOKIE', '')))"

Integration Examples¶

With Foundation Config¶

from provide.foundation import config
from pyvider.rpcplugin.security import MagicCookie

# Load cookie from Foundation configuration
app_config = config.get_config()
cookie = MagicCookie.from_config(
    app_config.plugin_magic_cookie,
    auto_generate=True
)

With Process Isolation¶

# Combine with process isolation
isolator = ProcessIsolator(
    sandbox_config=SandboxConfig(
        magic_cookie=cookie.value,
        require_authentication=True
    )
)

Next Steps¶

mTLS Configuration - Certificate-based authentication for network communication
Process Isolation - Secure plugin sandboxing
Certificate Management - PKI for advanced security scenarios
Security Overview - Complete security architecture guide