​
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:

  1. Server Level: Most specific, highest precedence
  2. Registry Level: Shared across servers in registry
  3. 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:

  1. Input Validation: Validate configuration structure and syntax
  2. Context Preparation: Prepare variables and secrets for each context
  3. Template Compilation: Compile templates with proper secret handling
  4. Context Processing: Generate context-specific configurations
  5. Security Validation: Ensure no secrets leak into display contexts
  6. 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

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

​
Development Best Practices

  1. Clear Context Boundaries: Maintain clear separation between display and copy contexts
  2. Consistent Redaction: Use consistent redaction patterns across all components
  3. Error Handling: Implement proper error handling for secret access failures
  4. Testing: Comprehensive testing of secret handling in all contexts
  5. 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:

  1. Check context processing logic
  2. Verify redaction rules are applied
  3. Validate template processing
  4. 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:

  1. Verify copy context is used
  2. Check secret unwrapping logic
  3. Validate template interpolation
  4. 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:

  1. Check secret exists at appropriate level
  2. Verify template syntax
  3. Validate precedence rules
  4. 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:

  1. Audit Existing Secrets: Identify all secrets in current configurations
  2. Implement Redaction: Add proper redaction logic to display contexts
  3. Context Separation: Separate display and copy contexts
  4. Template Migration: Update templates to use new secret syntax
  5. Testing: Comprehensive testing of secret handling
  6. 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

  1. Advanced Redaction: Context-aware redaction based on secret content
  2. Secret Versioning: Support for secret versions and rollback
  3. Integration Encryption: Encrypted secret transmission to external tools
  4. Biometric Access: Biometric authentication for secret access
  5. 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