_headers Validation Check Implementation

Date: January 21, 2026
Issue: #215 - Add an npm check to _headers
Status: ✅ Complete

What Was Created

1. Validation Script

File: tooling/scripts/validate-headers.js

A Node.js script that validates the Content Security Policy (CSP) in public/_headers by:

• Scanning source code for external URLs (http, https, ws, wss)
• Extracting domains from those URLs
• Checking if each domain is allowed in the CSP
• Reporting missing or misconfigured domains

Features:

• Automatic protocol handling (https://, http://, wss://, etc.)
• Wildcard domain support (*.example.com)
• Smart categorization of URLs by CSP directive
• Color-coded output for easy reading
• Detailed error messages with suggestions

2. NPM Scripts

File: package.json

Added two npm commands:

# Run the _headers validation check
npm run validate:headers

# Automatic check as part of the main validation pipeline
npm run validate

The validation is integrated into the pre-deployment validation - it now runs before:

• Unit tests
• Code formatting checks
• Linting

This ensures CSP violations are caught early in development.

3. Documentation

File: docs/engineering/deployment/app/HEADERS_VALIDATION.md

Comprehensive guide including:

• How the validation works
• When to update _headers
• CSP directive reference
• Current domains in use
• Troubleshooting guide
• Common mistakes and best practices

How to Use

Before Making Changes

# Check current state
npm run validate:headers

When Adding New External URLs/APIs

1. Add the URL to your code (fetch, script tag, etc.)
2. Run validation: npm run validate:headers
3. If the domain isn't in CSP, add it to public/_headers
4. Rerun validation to confirm

Example: Adding a New API

If you want to add Google Analytics:

// In your code
const script = document.createElement('script');
script.src = 'https://www.googletagmanager.com/gtag/js?id=GA-123456';

Run validation:

npm run validate:headers

Output will show:

✗ www.googletagmanager.com
Suggestion: Add missing domains to CSP script-src in public/_headers

Then update public/_headers to add it to script-src:

script-src 'self' ... https://www.googletagmanager.com ...

Integration Points

Development Workflow

• Automatically catches CSP issues before they reach production
• Part of the standard npm run validate pipeline
• Fails CI/CD if domains are missing

Pre-Deployment Check

• Runs as part of npm run validate
• Must pass before deployment
• Prevents security policy violations

Post-Deployment Check (Future)

• Can be extended to verify deployed _headers match source
• Could verify CSP headers are being served correctly by Cloudflare
• Could validate response headers in production

Known Limitations

False Positives

The script flags all external URLs found in code, including:

• Seed data in src/lib/seedVenues.js
• Example domains in comments
• Test data
• Backend-only scripts

These are safe to ignore if they're not actually fetched in the browser.

Limited to Frontend Code

Currently only scans:

• src/ directory (frontend code)
• scripts/ directory (automation)

Backend Cloud Functions are not included (they don't need CSP).

Files Changed

File	Change	Purpose
tooling/scripts/validate-headers.js	Created	CSP validation logic
package.json	Updated	Added npm scripts
docs/engineering/deployment/app/HEADERS_VALIDATION.md	Created	Documentation

Testing

The script has been tested and correctly:

• ✅ Identifies domains in CSP
• ✅ Matches exact domains
• ✅ Handles wildcard domains (*.example.com)
• ✅ Handles protocol variants
• ✅ Reports missing domains
• ✅ Integrates with npm validate pipeline

Next Steps

To maintain this validation:

1. Run before commits: Always run npm run validate before committing code that adds external URLs
2. Review CSP updates: When updating public/_headers, verify the domains are needed
3. Keep documentation updated: If CSP changes, update the domain list in HEADERS_VALIDATION.md
4. Consider post-deployment checks: In the future, add automated verification that deployed _headers are correct

References

• Issue: #215
• CSP Documentation: docs/engineering/deployment/app/DEPLOYMENT.md
• Headers File: public/_headers
• Validation Script: tooling/scripts/validate-headers.js