Secret Handling Guide

This guide provides a comprehensive overview of secret handling in Pylee, focusing on display redaction logic, configuration generation, and secure management practices across different contexts and components.

Overview

Pylee’s secret handling system is designed to provide maximum security while maintaining usability. The system distinguishes between different contexts where secrets might be used and applies appropriate security measures for each context.

Key Principles

Context-Aware Security: Different contexts require different levels of secret exposure
Secure by Default: Secrets are masked in display contexts by default
Flexible Access: Full secret values available when needed for functionality
Audit Trail: All secret access is logged and auditable
Multi-Layer Protection: Multiple security mechanisms work together

Secret Handling Contexts

Display Context

Used for showing configuration in user interfaces with secrets properly masked:

{
  "displayContext": {
    "API_KEY": "[redacted]",
    "DATABASE_URL": "postgresql://user:[redacted]@host:5432/db",
    "JWT_SECRET": "[redacted]",
    "CONNECTION_STRING": "Server=host;Database=db;User=user;Password=[redacted]"
  }
}

Characteristics:

All secret values are replaced with [redacted]
Maintains configuration structure for readability
Safe for logging and UI display
Prevents accidental secret exposure

Copy Context

Provides full configuration values for copying to clipboard or external tools:

{
  "copyContext": {
    "API_KEY": "sk-1234567890abcdef",
    "DATABASE_URL": "postgresql://user:secret123@host:5432/db",
    "JWT_SECRET": "jwt-secret-key-here",
    "CONNECTION_STRING": "Server=host;Database=db;User=user;Password=actual-password"
  }
}

Characteristics:

Contains actual secret values
Used for clipboard operations
Enables external tool integration
Requires explicit user action

Execution Context

Contains fully resolved configuration for runtime execution:

{
  "executionContext": {
    "API_KEY": "sk-1234567890abcdef",
    "DATABASE_URL": "postgresql://user:secret123@host:5432/db",
    "JWT_SECRET": "jwt-secret-key-here",
    "COMPUTED_HASH": "abc123def456",
    "RUNTIME_TOKEN": "generated-at-runtime"
  }
}

Characteristics:

Full secret values for application execution
May include computed or derived values
Used internally by Pylee components
Never exposed in user interfaces

Configuration Generation

Dual-Context Processing

Pylee generates configurations in multiple contexts simultaneously:

{
  "configurationGeneration": {
    "input": {
      "template": "Bearer {secret.API_KEY}",
      "context": {
        "secret.API_KEY": "sk-1234567890abcdef"
      }
    },
    "outputs": {
      "display": "Bearer [redacted]",
      "copy": "Bearer sk-1234567890abcdef",
      "execution": "Bearer sk-1234567890abcdef"
    }
  }
}

Template Interpolation with Secret Handling

Templates are processed differently based on context:

{
  "templateProcessing": {
    "template": "postgresql://{DB_USER}:{secret.DB_PASSWORD}@{DB_HOST}:5432/{DB_NAME}",
    "variables": {
      "DB_USER": "app_user",
      "DB_HOST": "localhost",
      "DB_NAME": "myapp"
    },
    "secrets": {
      "DB_PASSWORD": "complex-password-123"
    },
    "results": {
      "display": "postgresql://app_user:[redacted]@localhost:5432/myapp",
      "copy": "postgresql://app_user:complex-password-123@localhost:5432/myapp"
    }
  }
}

Component Integration

ConnectButton Component

The ConnectButton component exemplifies proper secret handling:

{
  "connectButton": {
    "displayConfiguration": {
      "command": "docker run -e API_KEY=[redacted] -e DEBUG=true myapp",
      "environment": {
        "API_KEY": "[redacted]",
        "DATABASE_URL": "postgresql://user:[redacted]@host:5432/db",
        "DEBUG": "true"
      }
    },
    "copyConfiguration": {
      "command": "docker run -e API_KEY=sk-1234567890abcdef -e DEBUG=true myapp",
      "environment": {
        "API_KEY": "sk-1234567890abcdef",
        "DATABASE_URL": "postgresql://user:secret123@host:5432/db",
        "DEBUG": "true"
      }
    }
  }
}

URL Handler Integration

URL handlers receive full configuration for external tool integration:

{
  "urlHandlers": {
    "cursor": {
      "displayUrl": "vscode://file{PROJECT_PATH}",
      "actualUrl": "vscode://file/path/to/project",
      "environment": {
        "API_KEY": "sk-1234567890abcdef",
        "DATABASE_URL": "postgresql://user:secret123@host:5432/db",
        "WORKSPACE_PATH": "/path/to/project"
      }
    },
    "code": {
      "displayUrl": "code://file{PROJECT_PATH}",
      "actualUrl": "code://file/path/to/project",
      "environment": {
        "development": "true",
        "API_KEY": "sk-1234567890abcdef"
      }
    }
  }
}

Multi-Level Secret Management

Precedence Hierarchy

Secrets are resolved with the following precedence:

Server Level: Most specific, highest precedence
Registry Level: Shared across servers in registry
Organization Level: Global organizational defaults

{
  "secretPrecedence": {
    "organization": {
      "secrets": {
        "GLOBAL_API_KEY": "org-key-123",
        "SHARED_SECRET": "org-shared-secret"
      }
    },
    "registry": {
      "secrets": {
        "SHARED_SECRET": "registry-shared-secret",
        "REGISTRY_TOKEN": "registry-token-456"
      }
    },
    "server": {
      "secrets": {
        "LOCAL_API_KEY": "server-key-789",
        "SHARED_SECRET": "server-shared-secret"
      }
    },
    "resolved": {
      "GLOBAL_API_KEY": "org-key-123",
      "SHARED_SECRET": "server-shared-secret",
      "REGISTRY_TOKEN": "registry-token-456",
      "LOCAL_API_KEY": "server-key-789"
    }
  }
}

Secret vs Variable Precedence

When both secrets and variables exist with the same name, secrets take precedence:

{
  "nameConflictResolution": {
    "configuration": {
      "variables": {
        "AUTH_TOKEN": "public-token"
      },
      "secrets": {
        "AUTH_TOKEN": "secret-token"
      }
    },
    "templates": {
      "unprefixed": "{AUTH_TOKEN}",
      "explicit_var": "{var.AUTH_TOKEN}",
      "explicit_secret": "{secret.AUTH_TOKEN}"
    },
    "resolution": {
      "unprefixed": "secret-token",
      "explicit_var": "public-token",
      "explicit_secret": "secret-token"
    }
  }
}

Security Implementation

Redaction Logic

The redaction system uses multiple strategies:

{
  "redactionStrategies": {
    "simpleRedaction": {
      "input": "sk-1234567890abcdef",
      "output": "[redacted]"
    },
    "partialRedaction": {
      "input": "very-long-secret-value-here",
      "output": "very-***-here"
    },
    "structuredRedaction": {
      "input": "postgresql://user:password@host:5432/db",
      "output": "postgresql://user:[redacted]@host:5432/db"
    },
    "jsonRedaction": {
      "input": {
        "api_key": "sk-123",
        "database_url": "postgresql://user:pass@host/db"
      },
      "output": {
        "api_key": "[redacted]",
        "database_url": "postgresql://user:[redacted]@host/db"
      }
    }
  }
}

Access Control

Secret access is controlled through multiple mechanisms:

{
  "accessControl": {
    "contextBasedAccess": {
      "display": {
        "allowedOperations": ["read_masked"],
        "restrictions": ["no_plain_text", "no_export"]
      },
      "copy": {
        "allowedOperations": ["read_plain", "clipboard_copy"],
        "restrictions": ["user_initiated_only"]
      },
      "execution": {
        "allowedOperations": ["read_plain", "runtime_access"],
        "restrictions": ["internal_only"]
      }
    },
    "roleBasedAccess": {
      "viewer": {
        "contexts": ["display"],
        "permissions": ["read_masked"]
      },
      "developer": {
        "contexts": ["display", "copy"],
        "permissions": ["read_masked", "copy_plain"]
      },
      "admin": {
        "contexts": ["display", "copy", "execution"],
        "permissions": ["read_masked", "copy_plain", "runtime_access"]
      }
    }
  }
}

Configuration Processing Pipeline

Processing Flow

The configuration processing follows a structured pipeline:

Input Validation: Validate configuration structure and syntax
Context Preparation: Prepare variables and secrets for each context
Template Compilation: Compile templates with proper secret handling
Context Processing: Generate context-specific configurations
Security Validation: Ensure no secrets leak into display contexts
Output Generation: Produce final configurations for each context

{
  "processingPipeline": {
    "input": {
      "template": "https://{HOST}/api?key={secret.API_KEY}",
      "variables": { "HOST": "api.example.com" },
      "secrets": { "API_KEY": "sk-1234567890abcdef" }
    },
    "stages": {
      "validation": {
        "templateSyntax": "valid",
        "variableReferences": "valid",
        "secretReferences": "valid"
      },
      "contextPreparation": {
        "display": {
          "HOST": "api.example.com",
          "secret.API_KEY": "[redacted]"
        },
        "copy": {
          "HOST": "api.example.com",
          "secret.API_KEY": "sk-1234567890abcdef"
        }
      },
      "processing": {
        "display": "https://api.example.com/api?key=[redacted]",
        "copy": "https://api.example.com/api?key=sk-1234567890abcdef"
      },
      "validation": {
        "display": "no_secrets_exposed",
        "copy": "secrets_available"
      }
    }
  }
}

Advanced Features

Dynamic Secret Generation

Some secrets are generated dynamically:

{
  "dynamicSecrets": {
    "sessionToken": {
      "generator": "jwt",
      "params": {
        "secret": "{secret.JWT_SECRET}",
        "payload": {
          "user": "{var.USER_ID}",
          "exp": "{computed.EXPIRATION}"
        }
      }
    },
    "apiHash": {
      "generator": "hmac",
      "params": {
        "secret": "{secret.HMAC_KEY}",
        "message": "{var.API_ENDPOINT}"
      }
    }
  }
}

Secret Rotation Support

The system supports automatic secret rotation:

{
  "secretRotation": {
    "policies": {
      "api_keys": {
        "rotation_interval": "30d",
        "warning_period": "7d",
        "auto_rotate": true
      },
      "database_passwords": {
        "rotation_interval": "90d",
        "warning_period": "14d",
        "auto_rotate": false
      }
    },
    "notifications": {
      "rotation_warning": {
        "channels": ["email", "webhook"],
        "message": "Secret {secret_name} will expire in {days} days"
      }
    }
  }
}

Audit and Monitoring

All secret access is logged and monitored:

{
  "auditLogging": {
    "events": [
      {
        "timestamp": "2024-01-15T10:30:00Z",
        "event": "secret_accessed",
        "context": "copy",
        "secret_name": "api_key",
        "user": "developer@company.com",
        "component": "ConnectButton"
      },
      {
        "timestamp": "2024-01-15T10:31:00Z",
        "event": "configuration_generated",
        "context": "display",
        "template": "Bearer {secret.API_KEY}",
        "secrets_redacted": ["API_KEY"]
      }
    ],
    "monitoring": {
      "metrics": {
        "secret_access_count": 1247,
        "redaction_success_rate": 99.97,
        "configuration_generation_time": "12ms"
      },
      "alerts": {
        "unusual_access_pattern": false,
        "redaction_failure": false,
        "performance_degradation": false
      }
    }
  }
}

Best Practices

Security Best Practices

Never Log Secrets: Ensure secrets are never written to logs in plain text
Context Validation: Always validate that secrets are properly redacted in display contexts
Access Control: Implement proper access controls based on user roles and contexts
Regular Audits: Conduct regular audits of secret access patterns
Rotation Policies: Implement and enforce regular secret rotation

Development Best Practices

Clear Context Boundaries: Maintain clear separation between display and copy contexts
Consistent Redaction: Use consistent redaction patterns across all components
Error Handling: Implement proper error handling for secret access failures
Testing: Comprehensive testing of secret handling in all contexts
Documentation: Document secret handling patterns and requirements

Implementation Guidelines

{
  "implementationGuidelines": {
    "componentDesign": {
      "separateContexts": "Always separate display and copy contexts",
      "secureDefaults": "Default to secure (redacted) display",
      "explicitActions": "Require explicit user actions for secret access"
    },
    "templateHandling": {
      "contextAware": "Process templates differently per context",
      "secretDetection": "Automatically detect and handle secret references",
      "fallbackSafe": "Safe fallbacks when secrets are unavailable"
    },
    "errorHandling": {
      "gracefulDegradation": "Gracefully handle secret access failures",
      "userFeedback": "Provide clear feedback on secret-related errors",
      "auditTrail": "Log all secret-related errors for analysis"
    }
  }
}

Troubleshooting

Common Issues

Secrets Not Redacting

Problem: Secrets appearing in plain text in display contexts Symptoms:

UI shows actual secret values
Logs contain plain text secrets
Copy functionality not working

Solutions:

Check context processing logic
Verify redaction rules are applied
Validate template processing
Review component implementation

Copy Functionality Issues

Problem: Copy operations not including actual secret values Symptoms:

Copied configuration contains [redacted]
External tools receive masked values
Integration failures

Solutions:

Verify copy context is used
Check secret unwrapping logic
Validate template interpolation
Test context switching

Template Resolution Failures

Problem: Templates not resolving secret references Symptoms:

Templates show {secret.NAME} instead of values
Configuration generation fails
Missing secret values in output

Solutions:

Check secret exists at appropriate level
Verify template syntax
Validate precedence rules
Test secret access permissions

Debugging Tools

{
  "debuggingTools": {
    "secretAudit": {
      "command": "pylee debug secrets",
      "output": "Lists all secrets and their access patterns"
    },
    "contextValidation": {
      "command": "pylee validate context",
      "output": "Validates secret handling in all contexts"
    },
    "templateTesting": {
      "command": "pylee test templates",
      "output": "Tests template interpolation with secret handling"
    }
  }
}

Migration and Upgrade

From Legacy Systems

When migrating from systems without proper secret handling:

Audit Existing Secrets: Identify all secrets in current configurations
Implement Redaction: Add proper redaction logic to display contexts
Context Separation: Separate display and copy contexts
Template Migration: Update templates to use new secret syntax
Testing: Comprehensive testing of secret handling
Security Review: Conduct security review of new implementation

Upgrade Considerations

{
  "upgradeConsiderations": {
    "backwardCompatibility": {
      "legacyTemplates": "Support for old template syntax",
      "migrationTools": "Automated migration utilities",
      "fallbackModes": "Fallback to secure defaults"
    },
    "securityImprovements": {
      "enhancedRedaction": "Improved redaction algorithms",
      "betterAuditing": "Enhanced audit logging",
      "strongerAccess": "Stronger access controls"
    }
  }
}

Future Enhancements

Planned Features

Advanced Redaction: Context-aware redaction based on secret content
Secret Versioning: Support for secret versions and rollback
Integration Encryption: Encrypted secret transmission to external tools
Biometric Access: Biometric authentication for secret access
AI-Powered Monitoring: AI-based anomaly detection for secret access

Roadmap

{
  "roadmap": {
    "shortTerm": {
      "enhancedAuditing": "Q1 2024",
      "improvedRedaction": "Q2 2024",
      "betterIntegration": "Q2 2024"
    },
    "longTerm": {
      "secretVersioning": "Q4 2024",
      "aiMonitoring": "Q1 2025",
      "biometricAccess": "Q2 2025"
    }
  }
}

Conclusion

Pylee’s secret handling system provides a comprehensive, secure, and flexible approach to managing sensitive configuration data. By implementing context-aware processing, secure redaction, and proper access controls, the system ensures that secrets are protected while maintaining the functionality needed for development and deployment workflows. The key to successful secret management in Pylee is understanding the different contexts and implementing appropriate security measures for each. Regular auditing, proper testing, and adherence to security best practices ensure that the system remains secure and functional over time.

Next Steps

Learn about Configuration Management for advanced configuration scenarios
Explore Template Interpolation for detailed template syntax
Review Variables for non-sensitive configuration
Check Secrets for basic secret management

Get Started

Using Pylee

Understanding Pylee

MCP Servers

Support

​Secret Handling Guide

​Overview

​Key Principles

​Secret Handling Contexts

​Display Context

​Copy Context

​Execution Context

​Configuration Generation

​Dual-Context Processing

​Template Interpolation with Secret Handling

​Component Integration

​ConnectButton Component

​URL Handler Integration

​Multi-Level Secret Management

​Precedence Hierarchy

​Secret vs Variable Precedence

​Security Implementation

​Redaction Logic

​Access Control

​Configuration Processing Pipeline

​Processing Flow

​Advanced Features

​Dynamic Secret Generation

​Secret Rotation Support

​Audit and Monitoring

​Best Practices

​Security Best Practices

​Development Best Practices

​Implementation Guidelines

​Troubleshooting

​Common Issues

​Secrets Not Redacting

​Copy Functionality Issues

​Template Resolution Failures

​Debugging Tools

​Migration and Upgrade

​From Legacy Systems

​Upgrade Considerations

​Future Enhancements

​Planned Features

​Roadmap

​Conclusion

​Next Steps

Secret Handling Guide

Overview

Key Principles

Secret Handling Contexts

Display Context

Copy Context

Execution Context

Configuration Generation

Dual-Context Processing

Template Interpolation with Secret Handling

Component Integration

ConnectButton Component

URL Handler Integration

Multi-Level Secret Management

Precedence Hierarchy

Secret vs Variable Precedence

Security Implementation

Redaction Logic

Access Control

Configuration Processing Pipeline

Processing Flow

Advanced Features

Dynamic Secret Generation

Secret Rotation Support

Audit and Monitoring

Best Practices

Security Best Practices

Development Best Practices

Implementation Guidelines

Troubleshooting

Common Issues

Secrets Not Redacting

Copy Functionality Issues

Template Resolution Failures

Debugging Tools

Migration and Upgrade

From Legacy Systems

Upgrade Considerations

Future Enhancements

Planned Features

Roadmap

Conclusion

Next Steps