🔐 Backend Secrets Management

Proper secrets management is crucial for application security and operational integrity. This guide covers how to securely handle API keys, database credentials, and other sensitive information when working with backends in AppStruct.

---

Overview

What are Backend Secrets?

Backend secrets are sensitive pieces of information required to connect and authenticate with external services:

• API Keys: Authentication tokens for external services
• Database Credentials: Connection strings, usernames, passwords
• OAuth Credentials: Client IDs, client secrets for social authentication
• Webhook Secrets: Verification tokens for webhook endpoints
• Encryption Keys: Keys for data encryption and signing
• Service Account Keys: Credentials for service-to-service authentication

Why Secrets Management Matters

• Security: Prevent unauthorized access to your data and services
• Compliance: Meet regulatory requirements (GDPR, HIPAA, SOX)
• Operational Safety: Avoid service disruptions from compromised credentials
• Access Control: Manage who can access what secrets
• Audit Trail: Track secret usage and changes
• Rotation: Regularly update credentials for security

---

AppStruct Secrets Management

Built-in Secrets Vault

AppStruct provides a secure, encrypted secrets management system:

• AES-256 Encryption: All secrets encrypted at rest
• Environment Separation: Different secrets for dev/staging/production
• Role-Based Access: Control who can view/edit secrets
• Audit Logging: Track all secret access and modifications
• Automatic Rotation: Built-in support for rotating API keys
• Backup & Recovery: Secure backup of secrets with encryption

Accessing Secrets Manager

1. Navigate to Project Settings:

   • Open your AppStruct project
   • Go to Settings → Backend Configuration
   • Select Secrets Management

2. Environment Selection:

   • Choose your target environment (Development, Staging, Production)
   • Each environment maintains separate secrets
   • Changes require appropriate permissions

---

Managing Different Types of Secrets

Database Credentials

AppStruct Native Database:

• No Manual Setup Required: Credentials managed automatically
• Automatic Rotation: Keys rotated monthly for security
• Environment Isolation: Each environment has separate credentials

Supabase Integration:

{
  "supabase_url": "https://your-project.supabase.co",
  "supabase_anon_key": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "supabase_service_key": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Firebase Integration:

{
  "firebase_project_id": "your-project-id",
  "firebase_api_key": "AIzaSyCG-iX9X...",
  "firebase_auth_domain": "your-project.firebaseapp.com",
  "firebase_storage_bucket": "your-project.appspot.com"
}

API Keys Management

External Service APIs:

• Stripe: Payment processing keys
• SendGrid: Email service keys
• Twilio: SMS/communication keys
• Google Maps: Geolocation service keys
• OpenAI: AI/ML service keys

Key Storage Format:

{
  "stripe_publishable_key": "pk_live_...",
  "stripe_secret_key": "sk_live_...",
  "sendgrid_api_key": "SG.abc123...",
  "twilio_account_sid": "AC123...",
  "twilio_auth_token": "abc123...",
  "google_maps_api_key": "AIza..."
}

OAuth Credentials

Social Authentication Setup:

{
  "google_oauth": {
    "client_id": "123456789.apps.googleusercontent.com",
    "client_secret": "abc123...",
    "redirect_uri": "https://yourapp.com/auth/callback"
  },
  "facebook_oauth": {
    "app_id": "123456789",
    "app_secret": "abc123...",
    "redirect_uri": "https://yourapp.com/auth/facebook"
  },
  "github_oauth": {
    "client_id": "abc123...",
    "client_secret": "def456...",
    "redirect_uri": "https://yourapp.com/auth/github"
  }
}

Webhook Secrets

Verification Tokens:

{
  "stripe_webhook_secret": "whsec_abc123...",
  "github_webhook_secret": "abc123...",
  "zapier_webhook_secret": "def456...",
  "custom_webhook_secret": "ghi789..."
}

---

Environment Management

Environment Separation

Development Environment:

• Test API Keys: Use sandbox/test keys from services
• Local Database: Development database with test data
• Debug Mode: Enhanced logging for troubleshooting
• Relaxed Security: Easier testing and development

Staging Environment:

• Production-like Setup: Mirror production configuration
• Test Data: Realistic but non-sensitive data
• Performance Testing: Load testing with production keys
• Final Validation: Last check before production deployment

Production Environment:

• Live API Keys: Real, production-ready credentials
• Secure Configuration: Maximum security settings
• Monitoring: Comprehensive logging and alerting
• Backup & Recovery: Automated backup systems

Environment-Specific Configuration

Automated Environment Detection:

// AppStruct automatically detects environment
const environment = AppStruct.getEnvironment(); // 'dev', 'staging', 'prod'

// Load appropriate secrets
const apiKey = AppStruct.getSecret(`stripe_key_${environment}`);
const dbUrl = AppStruct.getSecret(`database_url_${environment}`);

Manual Environment Override:

// Override environment for testing
AppStruct.setEnvironment('staging');
const secrets = AppStruct.getAllSecrets();

---

Security Best Practices

Secret Creation & Storage

Strong Secret Generation:

• Minimum Length: At least 32 characters for API keys
• Random Generation: Use cryptographically secure random generators
• Unique Secrets: Never reuse secrets across services or environments
• Complex Passwords: Mix of uppercase, lowercase, numbers, symbols

Secure Storage Principles:

• Encryption at Rest: All secrets encrypted with AES-256
• Encryption in Transit: TLS 1.3 for all secret transmissions
• Access Logging: Log all secret access with timestamps
• Principle of Least Privilege: Grant minimum necessary access

Access Control

Role-Based Permissions:

Role	View Secrets	Edit Secrets	Delete Secrets	Manage Users
Developer	✅ Dev only	✅ Dev only	❌	❌
Team Lead	✅ Dev + Staging	✅ Dev + Staging	✅ Dev only	❌
DevOps	✅ All environments	✅ All environments	✅ Dev + Staging	✅
Admin	✅ All environments	✅ All environments	✅ All environments	✅

Access Control Implementation:

// Check user permissions before secret access
const user = AppStruct.getCurrentUser();
const hasAccess = AppStruct.checkSecretPermission(user, 'stripe_key', 'read');

if (hasAccess) {
  const apiKey = AppStruct.getSecret('stripe_key');
} else {
  throw new Error('Insufficient permissions to access secret');
}

Secret Rotation

Automatic Rotation:

• Database Credentials: Rotated monthly
• API Keys: Rotated quarterly or based on service requirements
• OAuth Tokens: Rotated based on expiration
• Webhook Secrets: Rotated semi-annually

Manual Rotation Process:

1. Generate New Secret: Create new credential in external service
2. Update AppStruct: Add new secret to AppStruct vault
3. Deploy Changes: Update application to use new secret
4. Verify Functionality: Test all integrations work correctly
5. Revoke Old Secret: Remove old credential from external service
6. Update Documentation: Record rotation in audit logs

Rotation Workflow:

// Automated rotation workflow
const rotationService = AppStruct.getRotationService();

// Schedule rotation
rotationService.scheduleRotation('stripe_keys', {
  frequency: 'quarterly',
  notifyBefore: '7 days',
  autoRotate: true
});

// Manual rotation
await rotationService.rotateSecret('database_password', {
  generateNew: true,
  testConnection: true,
  rollbackOnFailure: true
});

---

Integration-Specific Secret Management

Supabase Secrets

Required Credentials:

• Project URL: Public, safe to expose in frontend
• Anon Key: Public, safe for client-side use
• Service Role Key: SECRET, server-side only
• Database Password: SECRET, direct database access

Security Configuration:

// Correct: Service key used server-side only
const supabaseAdmin = createClient(
  AppStruct.getSecret('supabase_url'),
  AppStruct.getSecret('supabase_service_key') // Server-side only
);

// Correct: Anon key for client-side
const supabaseClient = createClient(
  AppStruct.getSecret('supabase_url'),
  AppStruct.getSecret('supabase_anon_key') // Client-safe
);

RLS (Row Level Security) Configuration:

-- Enable RLS on sensitive tables
ALTER TABLE user_profiles ENABLE ROW LEVEL SECURITY;

-- Create policies for secure access
CREATE POLICY "Users can view own profile" ON user_profiles
FOR SELECT USING (auth.uid() = user_id);

CREATE POLICY "Users can update own profile" ON user_profiles
FOR UPDATE USING (auth.uid() = user_id);

Firebase Secrets

Configuration Object Security:

// Safe for client-side (public configuration)
const firebaseConfig = {
  apiKey: AppStruct.getSecret('firebase_api_key'),
  authDomain: AppStruct.getSecret('firebase_auth_domain'),
  projectId: AppStruct.getSecret('firebase_project_id'),
  storageBucket: AppStruct.getSecret('firebase_storage_bucket'),
  messagingSenderId: AppStruct.getSecret('firebase_messaging_sender_id'),
  appId: AppStruct.getSecret('firebase_app_id')
};

// Server-side only (admin SDK)
const adminConfig = {
  type: "service_account",
  project_id: AppStruct.getSecret('firebase_project_id'),
  private_key_id: AppStruct.getSecret('firebase_private_key_id'),
  private_key: AppStruct.getSecret('firebase_private_key'), // NEVER expose
  client_email: AppStruct.getSecret('firebase_client_email'),
  client_id: AppStruct.getSecret('firebase_client_id'),
  auth_uri: "https://accounts.google.com/o/oauth2/auth",
  token_uri: "https://oauth2.googleapis.com/token"
};

Security Rules Management:

// Deploy security rules with proper authentication
const admin = require('firebase-admin');
const serviceAccount = AppStruct.getSecret('firebase_service_account');

admin.initializeApp({
  credential: admin.credential.cert(serviceAccount),
  databaseURL: AppStruct.getSecret('firebase_database_url')
});

Third-Party API Secrets

Payment Processing (Stripe):

// Environment-specific keys
const stripeKey = AppStruct.getSecret(`stripe_${environment}_key`);
const stripe = require('stripe')(stripeKey);

// Webhook signature verification
const webhookSecret = AppStruct.getSecret('stripe_webhook_secret');
const signature = req.headers['stripe-signature'];
const event = stripe.webhooks.constructEvent(req.body, signature, webhookSecret);

Email Services (SendGrid):

// API key configuration
const sgMail = require('@sendgrid/mail');
sgMail.setApiKey(AppStruct.getSecret('sendgrid_api_key'));

// Template and sender verification
const message = {
  to: recipient,
  from: AppStruct.getSecret('sendgrid_verified_sender'),
  templateId: AppStruct.getSecret('sendgrid_template_id'),
  dynamicTemplateData: data
};

---

Compliance & Auditing

Regulatory Compliance

GDPR Requirements:

• Data Minimization: Store only necessary secrets
• Purpose Limitation: Use secrets only for intended purposes
• Encryption: Encrypt all personal data and access credentials
• Access Logging: Log all access to personal data systems
• Data Retention: Define retention periods for secrets

HIPAA Compliance:

• Administrative Safeguards: Assign security responsibility
• Physical Safeguards: Secure workstations and media
• Technical Safeguards: Access control and audit controls
• Encryption: Encrypt all PHI-related credentials

SOX Compliance:

• Access Controls: Restrict access to financial systems
• Change Management: Document all secret changes
• Segregation of Duties: Separate secret management roles
• Regular Audits: Periodic review of access and changes

Audit Logging

What Gets Logged:

• Secret Access: Who accessed which secrets when
• Secret Changes: All additions, modifications, deletions
• Permission Changes: Role and access modifications
• Failed Access Attempts: Security incident indicators
• Rotation Events: Automated and manual secret rotations

Log Format:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "event_type": "secret_access",
  "user_id": "user_123",
  "user_email": "[email protected]",
  "secret_name": "stripe_api_key",
  "environment": "production",
  "action": "read",
  "ip_address": "192.168.1.100",
  "user_agent": "AppStruct/1.0",
  "success": true
}

Audit Reports:

• Monthly Access Reports: Who accessed what secrets
• Change Summaries: All secret modifications
• Security Incidents: Failed access attempts and anomalies
• Compliance Reports: GDPR, HIPAA, SOX compliance status

---

Advanced Features

Secret Versioning

Version Control:

• Automatic Versioning: Every secret change creates a new version
• Rollback Capability: Revert to previous secret versions
• Version History: Track all changes with timestamps
• Diff Comparison: Compare different versions of secrets

Version Management:

// Get specific version of secret
const previousKey = AppStruct.getSecret('api_key', { version: 2 });

// List all versions
const versions = AppStruct.getSecretVersions('api_key');

// Rollback to previous version
await AppStruct.rollbackSecret('api_key', { toVersion: 2 });

Secret Dependencies

Dependency Tracking:

• Related Secrets: Track which secrets are used together
• Impact Analysis: Understand rotation effects
• Batch Updates: Update related secrets together
• Dependency Validation: Ensure dependent secrets are compatible

Dependency Configuration:

// Define secret dependencies
AppStruct.defineSecretDependency('stripe_api_key', [
  'stripe_webhook_secret',
  'stripe_publishable_key'
]);

// Batch rotation of dependent secrets
await AppStruct.rotateSecretGroup('stripe_keys');

Secret Templates

Template System:

• Service Templates: Pre-configured secret structures
• Environment Templates: Copy secrets across environments
• Project Templates: Standard secret setup for new projects
• Validation Rules: Ensure secrets meet requirements

Template Usage:

// Apply service template
await AppStruct.applySecretTemplate('stripe_integration', {
  environment: 'production',
  overrides: {
    'stripe_api_key': 'sk_live_custom_key'
  }
});

// Create environment from template
await AppStruct.createEnvironmentFromTemplate('staging', 'production', {
  excludeSecrets: ['stripe_secret_key'],
  transformKeys: (key) => key.replace('_prod_', '_staging_')
});

---

Troubleshooting

Common Issues

Secret Access Errors:

// Check if secret exists
if (!AppStruct.secretExists('api_key')) {
  console.error('Secret not found: api_key');
}

// Verify permissions
const hasPermission = AppStruct.checkSecretPermission(
  AppStruct.getCurrentUser(),
  'api_key',
  'read'
);

if (!hasPermission) {
  console.error('Insufficient permissions to access secret');
}

Environment Issues:

// Verify environment configuration
const currentEnv = AppStruct.getEnvironment();
console.log(`Current environment: ${currentEnv}`);

// List available secrets for environment
const secrets = AppStruct.listSecrets({ environment: currentEnv });
console.log('Available secrets:', secrets);

Connection Problems:

// Test secret validity
const testResult = await AppStruct.testSecret('database_url');
if (!testResult.valid) {
  console.error('Secret validation failed:', testResult.error);
}

// Validate all secrets for service
const validation = await AppStruct.validateServiceSecrets('stripe');
if (!validation.allValid) {
  console.error('Invalid secrets:', validation.invalid);
}

Error Resolution

Debugging Steps:

1. Check Secret Existence: Verify secret is properly stored
2. Validate Permissions: Ensure user has appropriate access
3. Test Environment: Confirm correct environment selection
4. Verify Format: Check secret format matches expectations
5. Check Rotation Status: Ensure secret hasn't expired or rotated

Error Handling:

try {
  const apiKey = AppStruct.getSecret('stripe_key');
  // Use API key
} catch (error) {
  if (error.code === 'SECRET_NOT_FOUND') {
    console.error('Secret not configured');
    // Handle missing secret
  } else if (error.code === 'PERMISSION_DENIED') {
    console.error('Insufficient permissions');
    // Handle permission error
  } else if (error.code === 'SECRET_EXPIRED') {
    console.error('Secret has expired');
    // Handle expired secret
  } else {
    console.error('Unknown error:', error);
    // Handle other errors
  }
}

---

Migration & Backup

Secret Migration

Between Environments:

// Copy secrets from production to staging
await AppStruct.copySecrets({
  from: 'production',
  to: 'staging',
  exclude: ['stripe_live_keys'],
  transform: (key, value) => {
    // Transform live keys to test keys
    if (key.includes('_live_')) {
      return key.replace('_live_', '_test_');
    }
    return key;
  }
});

Project Migration:

// Export secrets for migration
const secretsExport = await AppStruct.exportSecrets({
  environment: 'production',
  format: 'encrypted',
  password: 'secure_migration_password'
});

// Import to new project
await AppStruct.importSecrets(secretsExport, {
  password: 'secure_migration_password',
  overwrite: false,
  validate: true
});

Backup & Recovery

Automated Backups:

• Daily Backups: Encrypted backups of all secrets
• Cross-Region Storage: Backups stored in multiple regions
• Retention Policy: 90-day retention for compliance
• Integrity Checks: Regular backup validation

Manual Backup:

// Create backup
const backup = await AppStruct.createSecretBackup({
  environments: ['production', 'staging'],
  encryption: 'aes-256',
  compression: true
});

// Restore from backup
await AppStruct.restoreFromBackup(backup, {
  environment: 'production',
  verify: true,
  rollbackOnFailure: true
});

---

Best Practices Summary

Security

1. Never Hardcode Secrets: Always use the secrets management system
2. Use Strong Secrets: Generate cryptographically secure random secrets
3. Rotate Regularly: Implement automatic rotation where possible
4. Limit Access: Grant minimum necessary permissions
5. Monitor Usage: Track all secret access and changes

Operational

1. Environment Separation: Use different secrets for each environment
2. Document Dependencies: Track which secrets are used together
3. Test Thoroughly: Validate secrets after rotation or changes
4. Backup Regularly: Maintain encrypted backups of all secrets
5. Plan for Incidents: Have procedures for compromised secrets

Compliance

1. Audit Everything: Log all secret-related activities
2. Regular Reviews: Periodically review access and permissions
3. Data Classification: Classify secrets by sensitivity level
4. Retention Policies: Define how long to keep secret history
5. Incident Response: Have procedures for security incidents

---

Need Assistance?

Security Consultation:

• Contact [email protected] for security reviews
• Schedule security assessment of your secret management
• Get guidance on compliance requirements (GDPR, HIPAA, SOX)

Emergency Support:

• 24/7 support for security incidents
• Rapid secret rotation assistance
• Emergency access recovery
• Incident response coordination

Additional Resources:

• Security best practices documentation
• Compliance templates and checklists
• Video tutorials on secret management
• Community forum for security discussions