Secrets Management Guide

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Table of Contents

1. Overview
2. Secrets Inventory
3. Development Secrets
4. Production Secrets
5. Key Rotation Procedures
6. Access Control
7. Audit Logging
8. Emergency Procedures
9. Best Practices
10. Troubleshooting

​

Overview

• Where secrets are stored
• How to access secrets
• Key rotation procedures
• Access control policies
• Audit logging requirements

​

Secrets Inventory

​

Client-Side Secrets (Environment Variables)

​

Server-Side Secrets (Supabase Edge Functions)

​

Testing Secrets (Development Only)

​

Development Secrets

​

Local Development Setup

# Copy from template
cp .env.example .env.local

# Edit with your values
# ⚠️ NEVER commit .env.local

# Already in .gitignore
.env.local
.env*.local

# Supabase (Required)
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-anon-key

# Testing Only (Development)
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

​

Local Supabase Secrets

# Start Supabase locally
supabase start

# Secrets are auto-provided for local functions
# No manual setup needed

​

Production Secrets

​

Supabase Edge Function Secrets

# Link to production project
supabase link --project-ref {project-ref}

# Set secrets (email: use Entra and/or Gmail)
supabase secrets set TWILIO_ACCOUNT_SID=ACxxxxx
supabase secrets set TWILIO_AUTH_TOKEN=xxxxx
supabase secrets set TWILIO_PHONE_NUMBER=+1234567890
supabase secrets set LOVABLE_API_KEY=xxxxx

1. Go to Project Settings → Edge Functions → Secrets
2. Click Add Secret
3. Enter key and value
4. Click Save

supabase secrets list

supabase secrets unset GMAIL_SERVICE_ACCOUNT_JSON

​

Vercel Environment Variables

1. Go to Vercel Dashboard → Project → Settings → Environment Variables
2. Add variables:
   • VITE_SUPABASE_URL (Production)
   • VITE_SUPABASE_PUBLISHABLE_KEY (Production)
3. Do NOT add SUPABASE_SERVICE_ROLE_KEY (never in client)

• Set variables per environment (Production, Preview, Development)
• Use Production values for production deployments

​

Key Rotation Procedures

​

Supabase Service Role Key

1. Generate New Key:
   • Go to Supabase Dashboard → Settings → API
   • Click Reset service_role key
   • Copy new key (save securely)
2. Update Edge Functions:
   supabase secrets set SUPABASE_SERVICE_ROLE_KEY={new-key}
   
3. Update Test Environment:
   • Update .env.local with new key
   • Verify tests still pass
4. Verify Functions Work:
   • Test edge functions that use service role key
   • Check function logs for errors
5. Revoke Old Key:
   • Old key is automatically invalidated when reset

​

Entra Client Secret / Gmail Service Account

​

Twilio Credentials

1. Generate New Auth Token:
   • Go to Twilio Console → Account → API Keys & Tokens
   • Click Create new Auth Token
   • Copy new token
2. Update Supabase Secrets:
   supabase secrets set TWILIO_AUTH_TOKEN={new-token}
   
3. Deploy Edge Function:
   supabase functions deploy send-sms-notification
   
4. Test SMS Delivery:
   • Send test SMS
   • Verify delivery
5. Revoke Old Token:
   • Delete old token in Twilio console

​

Supabase Anon Key

1. Generate New Key:
   • Go to Supabase Dashboard → Settings → API
   • Click Reset anon key
   • Copy new key
2. Update Environment Variables:
   • Vercel: Update VITE_SUPABASE_PUBLISHABLE_KEY
   • Local: Update .env.local
3. Redeploy Application:
   • Vercel will auto-deploy with new key
   • Or manually trigger deployment
4. Verify Application Works:
   • Test authentication
   • Test database queries
   • Check for errors

​

Access Control

​

Who Can Access Secrets?

• Local developers only
• Never shared via chat/email
• Stored locally only

• Platform team members only
• Access via Supabase CLI (authenticated)
• Or Supabase Dashboard (with 2FA)

• Team members with project access
• Set via Vercel Dashboard
• Access logged in Vercel audit log

​

Access Policies

• Only grant access to those who need it
• Use separate accounts for different environments
• Require 2FA for production access
• Review access quarterly

• Quarterly review of who has access
• Remove access for team members who left
• Document access in secure location (not in code)

​

Audit Logging

​

Secret Access Logging

• Edge function invocations logged
• Secret access not directly logged (functions use secrets)
• Function execution logs available in dashboard

• Environment variable changes logged
• Access via Vercel audit log
• Review quarterly

​

What to Log

• Secret creation
• Secret updates
• Secret deletion
• Key rotations
• Access attempts (if available)

• 90 days for secret operations
• 1 year for security incidents
• Permanent for key rotations

​

Monitoring

• Unusual secret access patterns
• Failed authentication attempts
• Secret rotation events
• Edge function errors (may indicate secret issues)

​

Emergency Procedures

​

Compromised Secret

1. Immediately Rotate:
   • Generate new secret
   • Update in all locations
   • Revoke old secret
2. Assess Impact:
   • What data was accessible?
   • When was secret compromised?
   • Who had access?
3. Notify Team:
   • Alert security team
   • Document incident
   • Update security procedures if needed
4. Monitor:
   • Watch for unauthorized access
   • Review audit logs
   • Check for data breaches

​

Lost Secret

1. Regenerate:
   • Create new secret
   • Update all systems
   • Test functionality
2. Document:
   • Record when secret was lost
   • Document recovery steps
   • Update procedures if needed

​

Secret Rotation Failure

1. Rollback:
   • Revert to previous secret
   • Verify system works
   • Investigate failure
2. Fix Issue:
   • Identify root cause
   • Fix configuration
   • Retry rotation
3. Document:
   • Record failure and resolution
   • Update procedures
   • Add monitoring if needed

​

Best Practices

​

1. Secret Storage

• Store secrets in secure systems (Supabase Secrets, Vercel)
• Use .env.local for local development (gitignored)
• Rotate secrets regularly
• Use different secrets per environment

• Commit secrets to version control
• Share secrets via chat/email
• Hardcode secrets in code
• Use same secrets across environments

​

2. Secret Access

• Use principle of least privilege
• Require 2FA for production access
• Review access quarterly
• Document who has access

• Grant access unnecessarily
• Share accounts
• Store secrets in plain text files
• Leave secrets in code comments

​

3. Secret Rotation

• Rotate secrets regularly (90-180 days)
• Rotate immediately if compromised
• Test rotation in staging first
• Document rotation procedures

• Skip rotation
• Rotate without testing
• Use same secret forever
• Forget to update all locations

​

4. Monitoring

• Monitor secret access (if available)
• Set up alerts for unusual activity
• Review audit logs regularly
• Track secret rotation dates

• Ignore security alerts
• Skip audit log reviews
• Forget to monitor
• Assume secrets are safe

​

Troubleshooting

​

Issue: Edge Function Can’t Access Secret

• Function fails with “not configured” error
• Function returns 500 error

1. Verify secret is set:
   supabase secrets list
   
2. Check secret name matches exactly (case-sensitive)
3. Redeploy function after setting secret:
   supabase functions deploy {function-name}
   
4. Check function logs in Supabase dashboard

​

Issue: Secret Not Found in Production

• Function works locally but fails in production
• “Environment variable not set” error

1. Verify you’re linked to correct project:
   supabase projects list
   supabase link --project-ref {project-ref}
   
2. Set secret in production:
   supabase secrets set KEY=value --project-ref {project-ref}
   
3. Redeploy function to production

​

Issue: Service Role Key in Client Code

• Build warnings about service role key
• Security audit flags

1. Remove SUPABASE_SERVICE_ROLE_KEY from .env.local
2. Only use in test files: tests/**/*.ts
3. Never import in client code: src/**/*.tsx
4. Use VITE_SUPABASE_PUBLISHABLE_KEY in client

​

Issue: Secret Rotation Broke Function

• Function fails after secret rotation
• Authentication errors

1. Verify new secret is correct
2. Check secret name matches exactly
3. Redeploy function after rotation
4. Test function with new secret
5. Rollback if needed (revert to old secret)

​

Secret Management Checklist

​

Development Setup

• .env.local created from .env.example
• .env.local in .gitignore
• No secrets committed to version control
• Service role key only in test files

​

Production Setup

• All edge function secrets set in Supabase
• Vercel environment variables configured
• No service role key in client code
• Secrets rotated within last 90 days
• Access control reviewed
• 2FA enabled for production access

​

Ongoing Maintenance

• Quarterly secret rotation
• Quarterly access review
• Audit logs reviewed
• Monitoring alerts configured
• Emergency procedures documented

​

Related Documentation

• Environment Variables: docs/development/ENVIRONMENT_VARIABLES.md
• Supabase Setup: docs/integrations/SUPABASE_SETUP.md
• Edge Functions: docs/integrations/EDGE_FUNCTIONS.md
• Constitution: constitution.md §4.1 (Security)