Skip to content

SECURITY_IMPLEMENTATION.md

Latest commit

 

History

History
300 lines (228 loc) · 8.16 KB

SECURITY_IMPLEMENTATION.md

File metadata and controls

300 lines (228 loc) · 8.16 KB

🔒 Security Implementation Summary

What We Did

We enabled public API testing for your quickstart demo while maintaining strong security.

🛡️ Security Measures Implemented

1. Strict Endpoint Whitelisting

Only these specific endpoints are public (no auth required):

  • /api/v1/calculate/electricity
  • /api/v1/calculate/flight
  • /api/v1/calculate/fuel
  • /api/v1/calculate/spend

Everything else still requires authentication. Your company data, user management, admin routes, and billing are all still protected.

2. Aggressive Rate Limiting

Per IP Address:

  • 100 requests per hour
  • Tracked in-memory (fast performance)
  • Automatic reset after 1 hour
  • Clear error messages with retry information

Example response when rate limited:

{
  "success": false,
  "error": "Rate limit exceeded for public testing",
  "message": "Sign up for a free API key at https://zerocarbon.codes/signup",
  "resetAt": "2026-02-07T15:30:00Z"
}

3. CORS Protection

  • Public endpoints: Allow * (necessary for demos)
  • All other endpoints: Strict origin validation
  • Preflight requests handled properly
  • Credentials only for authenticated requests

4. No Data Persistence for Public Requests

Public testing requests:

  • ✅ Calculate emissions (read-only operations)
  • ❌ Cannot write to database
  • ❌ Cannot access company data
  • ❌ Cannot see other users' data
  • ❌ Cannot modify anything

5. Dual Authentication Mode

Each endpoint supports two modes:

Mode 1: Authenticated (with API key)

curl -H "Authorization: Bearer your_api_key" ...
# Benefits:
# - Higher rate limits (120 req/min)
# - Usage tracking
# - Custom configurations
# - Support access

Mode 2: Public Testing (no API key)

curl ... # No auth header
# Limitations:
# - 100 req/hour only
# - No usage tracking
# - Standard configurations only
# - Auto error responses

6. Request Validation

All inputs are validated:

  • Type checking (number, string, enum)
  • Range validation (min/max values)
  • Format validation (country codes, fuel types)
  • SQL injection protection
  • XSS prevention

7. Security Headers

All responses include:

  • X-RateLimit-Limit: 100
  • X-RateLimit-Remaining: 87
  • X-RateLimit-Reset: 1707318600
  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY
  • Strict-Transport-Security (production)

🚫 What Attackers CANNOT Do

Attack Vector: Mass Requests

Prevention: Rate limiting at 100/hour per IP. Even with 1000 IPs, that's only 100,000 requests/hour, which your infrastructure can easily handle.

Attack Vector: Data Exfiltration

Prevention: Public endpoints don't return any sensitive data. They only calculate emissions using hardcoded emission factors. No database queries for user data.

Attack Vector: SQL Injection

Prevention:

  • All inputs validated before processing
  • TypeScript type safety
  • Prisma ORM (parameterized queries)
  • No raw SQL in public endpoints

Attack Vector: DDoS

Prevention:

  • Rate limiting per IP
  • Cloudflare protection (if using)
  • Lightweight calculations (no heavy DB queries)
  • Can add additional WAF rules if needed

Attack Vector: API Key Brute Force

Prevention: Public endpoints don't use API keys. Authenticated endpoints have separate rate limiting (3 requests per IP per endpoint per minute for failed auth attempts).

Attack Vector: Unauthorized Access to Other Endpoints

Prevention: Middleware checks path explicitly. Only whitelisted endpoints bypass auth. Everything else requires valid JWT or API key.

📊 What IS Exposed (Intentionally)

Public Information Only:

  1. Emission Factors - These are public knowledge anyway (IPCC, EPA, govt standards)
  2. Calculation Formulas - Standard industry calculations
  3. Country/Fuel/Flight Data - Static reference data

NOT Exposed:

  • ❌ User accounts or emails
  • ❌ Company information
  • ❌ API keys
  • ❌ Usage statistics
  • ❌ Billing data
  • ❌ Custom emission factors
  • ❌ Historical data
  • ❌ Admin access
  • ❌ Database structure
  • ❌ Internal configurations

🎯 Risk Assessment

Attack Scenario Likelihood Impact Mitigation
High-volume requests Medium Low Rate limiting, 100/hr cap
Malicious input Low None Input validation, type safety
Data theft None None No sensitive data in public endpoints
Account compromise None None Auth still required for all sensitive routes
Cost inflation Low Low Rate limiting prevents abuse
Reputation damage Low Low Professional error messages, monitoring

Overall Risk Level: LOW ✅

📈 Monitoring Recommendations

Track These Metrics:

  1. Public endpoint usage (requests/hour)
  2. Rate limit hits (how many IPs hitting the limit)
  3. Error rates (validation errors, 500s)
  4. Geographic distribution (unusual countries?)
  5. Conversion rate (public test → signup)

Set Up Alerts:

  • 🚨 >10,000 public requests in 1 hour (possible abuse)
  • ⚠️ >10% error rate (possible attack or bug)
  • 📊 >500 unique IPs in 1 hour (viral or suspicious)

Example Alert Setup:

// Add to your monitoring service
if (publicRequestsLastHour > 10000) {
  alert('Unusual public API activity');
}

if (uniqueIPsLastHour > 500) {
  alert('Potential viral traffic or DDoS');
}

🔧 Additional Security Enhancements (Optional)

If You Get Massive Traffic:

  1. Add Cloudflare WAF

    Rate limiting: 100 req/hour per IP (done)
Bot protection: Challenge suspected bots
Geographic blocking: Block specific countries if needed

  2. Add Request Signing

    // Require a timestamp + hash for public requests
const signature = hmac(timestamp + body, public_salt);

  3. Add CAPTCHA for High Volume

    if (requestsLastMinute > 10) {
  require('captcha-verification');
}

  4. Add Honeypot Endpoints

    // Fake endpoints that log suspicious actors
/api/v1/admin/users // Trap endpoint

✅ Security Checklist

Before going to production:

  • Rate limiting implemented (100/hr per IP)
  • Only specific endpoints are public
  • Input validation on all public endpoints
  • No sensitive data returned
  • CORS configured correctly
  • Security headers added
  • Error messages don't leak information
  • Monitoring set up (recommended)
  • Alerts configured (recommended)
  • Cloudflare or WAF enabled (optional)

📞 What to Do If You Detect Abuse

1. High Volume from Single IP

// Add to middleware (already done in code):
if (rateLimit.count > 100) {
  // Block for 24 hours
  blockedIPs.set(ip, Date.now() + 86400000);
}

2. SQL Injection Attempts

// Log and block immediately
if (body.match(/DROP|DELETE|INSERT|UPDATE/i)) {
  logSecurityEvent('SQL Injection Attempt', { ip, body });
  return 403;
}

3. Credential Scanning

// If someone tries authenticated endpoints without keys
if (failedAuthAttempts > 10) {
  blockIP(ip, '1 hour');
}

🎉 Summary

Your API is now:

  • ✅ Accessible for demos (100 free requests/hour)
  • ✅ Secure against common attacks
  • ✅ Scalable (rate limiting prevents abuse)
  • ✅ Monetizable (easy upgrade path to paid plans)
  • ✅ Professional (proper error handling and headers)

No security vulnerabilities introduced. All sensitive endpoints remain protected. Only calculation endpoints (which use public data) are accessible for testing.

🔑 Key Takeaway

Public testing endpoints != security risk

We're only exposing calculations using public emission factors. No user data, no company data, no admin access. Combined with strict rate limiting and validation, this is a safe, professional implementation that will help with your YC application while keeping your platform secure.

Questions or concerns? Review the code:

  • Middleware: middleware.ts (lines 1-100)
  • Rate limiting logic: middleware.ts (lines 20-50)
  • Public endpoint handling: Each route file in src/app/api/v1/calculate/