Skip to content

SECURITY.md

Latest commit

 

History

History
340 lines (273 loc) · 9.2 KB

SECURITY.md

File metadata and controls

340 lines (273 loc) · 9.2 KB

Security Implementation Guide

This document outlines the comprehensive security measures implemented in the XueDAO application for Supabase integration and admin authentication.

🔐 Security Overview

The application implements a multi-layered security architecture with:

  • Supabase Integration Security: Enhanced client/server configurations with proper authentication flows
  • Admin Authentication: Email-based admin verification with enhanced validation
  • Rate Limiting: Request-based protection against abuse
  • Security Headers: Comprehensive HTTP security headers
  • Environment Validation: Runtime validation of required environment variables

🏗️ Architecture Security Components

1. Supabase Client Security

Client-Side Security (lib/supabase/client.ts)

// Enhanced security configuration
{
  auth: {
    persistSession: true,
    autoRefreshToken: true,
    detectSessionInUrl: true,
    flowType: 'pkce', // PKCE flow for enhanced security
    storageKey: 'sb-auth-token'
  },
  global: {
    headers: {
      'X-Client-Info': 'xuedao-web-client'
    }
  }
}

Security Features:

  • ✅ PKCE (Proof Key for Code Exchange) flow
  • ✅ Secure token storage in localStorage
  • ✅ Automatic token refresh
  • ✅ Environment variable validation
  • ✅ URL format validation

Server-Side Security (lib/supabase/server.ts)

// Secure cookie configuration
const secureOptions = {
  httpOnly: true,
  secure: process.env.NODE_ENV === 'production',
  sameSite: 'lax' as const,
  path: '/'
}

Security Features:

  • ✅ HTTP-only cookies for auth tokens
  • ✅ Secure cookies in production
  • ✅ SameSite protection against CSRF
  • ✅ Service role client for admin operations
  • ✅ Enhanced error handling

2. Admin Authentication Security

Multi-Layer Admin Validation

  1. Session Validation: Verify active Supabase session
  2. Email Verification: Check email confirmation status
  3. Admin Email List: Validate against environment variable list
  4. Rate Limiting: Prevent brute force attacks
  5. Security Headers: Validate request headers

Admin Email Configuration

# Environment variable (comma-separated)
ADMIN_EMAILS=admin1@example.com,admin2@example.com

Security Features:

  • ✅ Case-insensitive email matching
  • ✅ Email format validation
  • ✅ Sanitized email processing
  • ✅ Unauthorized access logging
  • ✅ Email verification requirement

3. Rate Limiting & Protection

Rate Limiting Configuration

// Different limits for different operations
const RATE_LIMIT_WINDOW = 15 * 60 * 1000 // 15 minutes
const MAX_ATTEMPTS = 100 // general operations
const ADMIN_MAX_ATTEMPTS = 1000 // admin operations

Protection Features:

  • ✅ IP-based rate limiting
  • ✅ Higher limits for admin operations
  • ✅ Automatic rate limit cleanup
  • ✅ Rate limit headers in responses
  • ✅ Memory-based storage (upgradeable to Redis)

4. Security Headers & Middleware

Enhanced Security Headers

// Comprehensive security headers
'X-Content-Type-Options': 'nosniff'
'X-Frame-Options': 'DENY'
'X-XSS-Protection': '1; mode=block'
'Strict-Transport-Security': 'max-age=31536000; includeSubDomains; preload'
'Content-Security-Policy': '...' // Comprehensive CSP

Content Security Policy (CSP)

  • ✅ Strict default source policy
  • ✅ Whitelisted external domains (Google Analytics, Supabase)
  • ✅ No unsafe inline scripts (except where necessary)
  • ✅ Upgrade insecure requests
  • ✅ Frame ancestors blocked

CORS Configuration

  • ✅ Origin-based validation
  • ✅ Development/production environment handling
  • ✅ Credentials support for authenticated requests
  • ✅ Proper preflight handling

🛡️ Security Validations

Environment Variable Validation

// Required environment variables
const required = [
  'NEXT_PUBLIC_SUPABASE_URL',
  'NEXT_PUBLIC_SUPABASE_ANON_KEY',
  'SUPABASE_SERVICE_ROLE_KEY',
  'ADMIN_EMAILS'
]

Request Validation

  • ✅ IP address extraction and validation
  • ✅ Required headers validation
  • ✅ Origin validation for CORS
  • ✅ Request method validation

Session Security

  • ✅ Session expiry validation
  • ✅ Email confirmation requirement
  • ✅ User existence validation
  • ✅ Admin permission verification

🔍 Monitoring & Logging

Security Event Logging

// Unauthorized access attempts
console.warn(`Unauthorized admin access attempt: ${user.email}`)

// Configuration errors
console.error('Missing required environment variables:', missing)

// Rate limiting violations
// Automatic logging with IP tracking

Performance Monitoring

  • ✅ Authentication response times
  • ✅ Rate limit hit rates
  • ✅ Failed authentication attempts
  • ✅ Admin access patterns

🚨 Threat Mitigation

Common Attack Vectors

1. Brute Force Attacks

Mitigation:

  • Rate limiting on authentication endpoints
  • Progressive delays for repeated failures
  • IP-based blocking
  • Admin operation logging

2. Session Hijacking

Mitigation:

  • HTTP-only cookies
  • Secure cookie flags in production
  • SameSite cookie protection
  • Token rotation through Supabase

3. Cross-Site Scripting (XSS)

Mitigation:

  • Comprehensive CSP headers
  • X-XSS-Protection headers
  • Input sanitization
  • Output encoding

4. Cross-Site Request Forgery (CSRF)

Mitigation:

  • SameSite cookie policy
  • Origin validation
  • CORS configuration
  • CSRF token implementation (via Supabase)

5. Privilege Escalation

Mitigation:

  • Multi-layer admin validation
  • Email verification requirements
  • Row Level Security (RLS) in Supabase
  • Service role key protection

⚙️ Configuration Security

Production Environment Setup

Required Environment Variables

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ... # Keep secret!

# Admin Configuration
ADMIN_EMAILS=admin@yourdomain.com,admin2@yourdomain.com

# Application URLs
NEXT_PUBLIC_SITE_URL=https://xuedao.xyz

Security Checklist

  • All environment variables are set
  • Service role key is kept secret
  • Admin emails are properly configured
  • HTTPS is enforced in production
  • Security headers are active
  • Rate limiting is configured
  • Monitoring is set up

Database Security (Supabase)

Row Level Security (RLS)

-- Enable RLS on all tables
ALTER TABLE applications ENABLE ROW LEVEL SECURITY;
ALTER TABLE jobs ENABLE ROW LEVEL SECURITY;

-- Example RLS policies
CREATE POLICY "Public read access" ON jobs
  FOR SELECT USING (status = 'approved');

CREATE POLICY "Admin full access" ON jobs
  FOR ALL USING (auth.email() = ANY(string_to_array(current_setting('app.admin_emails'), ',')));

Service Role Usage

  • ✅ Used only for admin operations
  • ✅ Bypasses RLS when necessary
  • ✅ Proper error handling
  • ✅ Audit logging for service role operations

🔧 Security Maintenance

Regular Security Tasks

Weekly

  • Review authentication logs
  • Check rate limiting effectiveness
  • Validate admin access patterns
  • Update security headers if needed

Monthly

  • Audit admin email list
  • Review security configurations
  • Check for security updates
  • Performance security analysis

Quarterly

  • Security penetration testing
  • Dependency security audit
  • Access control review
  • Incident response testing

Security Updates

Dependency Management

# Check for security vulnerabilities
bun audit

# Update Supabase client
bun update @supabase/ssr @supabase/supabase-js

Configuration Updates

  • Monitor Supabase security announcements
  • Update CSP headers for new domains
  • Review and update admin email list
  • Rotate service role keys periodically

🚨 Incident Response

Security Incident Checklist

Immediate Response

  1. Identify the security incident type
  2. Assess the impact and scope
  3. Isolate affected systems if necessary
  4. Document the incident timeline

Investigation

  1. Review authentication logs
  2. Check rate limiting logs
  3. Analyze admin access attempts
  4. Verify environment configurations

Remediation

  1. Patch identified vulnerabilities
  2. Update security configurations
  3. Rotate compromised credentials
  4. Enhance monitoring if needed

Post-Incident

  1. Conduct incident review
  2. Update security procedures
  3. Improve detection capabilities
  4. Document lessons learned

📚 Additional Security Resources

Supabase Security Documentation

Security Standards

🔒 Security is an ongoing process. Regular reviews and updates are essential for maintaining a secure application.