Enhanced Content Security Policy (CSP) Configuration #

XyPriss provides advanced Content Security Policy configuration with flexible directive support, allowing developers to create comprehensive security policies for their web applications.

Overview #

The Helmet middleware in XyPriss now supports fully customizable CSP directives using a flexible Record<string, any> type, enabling any CSP directive to be configured with any value type.

Basic Configuration #

Simple CSP Setup #

import { createServer } from 'xypriss';

const app = createServer({
    security: {
        helmet: {
            contentSecurityPolicy: {
                directives: {
                    defaultSrc: ["'self'"],
                    scriptSrc: ["'self'", "'unsafe-inline'"],
                    styleSrc: ["'self'", "'unsafe-inline'"],
                    imgSrc: ["'self'", "data:", "https:"],
                }
            }
        }
    }
});

Advanced CSP with Multiple Sources #

const app = createServer({
    security: {
        helmet: {
            contentSecurityPolicy: {
                directives: {
                    // Multiple source types
                    defaultSrc: ["'self'"],
                    scriptSrc: [
                        "'self'",
                        "'unsafe-inline'",
                        "'unsafe-eval'",
                        "https://cdn.example.com",
                        "https://api.stripe.com"
                        "https://api.nehonix.com"
                    ],
                    styleSrc: [
                        "'self'",
                        "'unsafe-inline'",
                        "https://fonts.googleapis.com"
                    ],
                    fontSrc: [
                        "'self'",
                        "https://fonts.gstatic.com",
                        "data:"
                    ],
                    imgSrc: [
                        "'self'",
                        "data:",
                        "https:",
                        "blob:"
                    ],
                    connectSrc: [
                        "'self'",
                        "https://api.example.com",
                        "wss://websocket.example.com"
                    ],
                    frameSrc: ["'none'"],
                    objectSrc: ["'none'"],
                    baseUri: ["'self'"],
                    formAction: ["'self'"],
                    frameAncestors: ["'none'"],
                    upgradeInsecureRequests: []
                }
            }
        }
    }
});

Flexible Directive Types #

String Directives #

contentSecurityPolicy: {
    directives: {
        // Single string value
        baseUri: "'self'",
        // Multiple values as array
        scriptSrc: ["'self'", "https://cdn.example.com"],
        // Special CSP keywords
        frameSrc: "'none'",
        objectSrc: "'none'"
    }
}

Array Directives #

contentSecurityPolicy: {
    directives: {
        // Multiple sources
        scriptSrc: [
            "'self'",
            "'unsafe-inline'",
            "https://cdn.example.com",
            "https://api.stripe.com"
        ],
        // Mixed protocols and domains
        connectSrc: [
            "'self'",
            "https://api.example.com",
            "wss://websocket.example.com"
        ]
    }
}

Special Directives #

contentSecurityPolicy: {
    directives: {
        // Empty array for boolean directives
        upgradeInsecureRequests: [],
        // Block all
        frameAncestors: "'none'",
        // Allow all (not recommended)
        imgSrc: ["*"],
        // Data URLs
        imgSrc: ["data:"],
        // Blob URLs
        imgSrc: ["blob:"]
    }
}

Real-World Examples #

E-commerce Application #

const eCommerceApp = createServer({
    security: {
        helmet: {
            contentSecurityPolicy: {
                directives: {
                    defaultSrc: ["'self'"],
                    scriptSrc: [
                        "'self'",
                        "'unsafe-inline'", // For inline event handlers
                        "https://js.stripe.com",
                        "https://cdn.example.com"
                    ],
                    styleSrc: [
                        "'self'",
                        "'unsafe-inline'",
                        "https://fonts.googleapis.com"
                    ],
                    fontSrc: [
                        "'self'",
                        "https://fonts.gstatic.com"
                    ],
                    imgSrc: [
                        "'self'",
                        "data:",
                        "https:",
                        "blob:"
                    ],
                    connectSrc: [
                        "'self'",
                        "https://api.stripe.com",
                        "https://api.example.com"
                    ],
                    frameSrc: [
                        "https://js.stripe.com",
                        "https://www.youtube.com"
                    ],
                    objectSrc: ["'none'"],
                    baseUri: ["'self'"],
                    formAction: ["'self'"],
                    frameAncestors: ["'none'"],
                    upgradeInsecureRequests: []
                }
            }
        }
    }
});

Single Page Application (SPA) #

const spaApp = createServer({
    security: {
        helmet: {
            contentSecurityPolicy: {
                directives: {
                    defaultSrc: ["'self'"],
                    scriptSrc: [
                        "'self'",
                        "'unsafe-eval'", // For webpack dev server
                        "https://cdn.jsdelivr.net"
                    ],
                    styleSrc: [
                        "'self'",
                        "'unsafe-inline'",
                        "https://fonts.googleapis.com"
                    ],
                    fontSrc: [
                        "'self'",
                        "https://fonts.gstatic.com",
                        "data:"
                    ],
                    imgSrc: [
                        "'self'",
                        "data:",
                        "https:",
                        "blob:"
                    ],
                    connectSrc: [
                        "'self'",
                        "https://api.example.com",
                        "wss://api.example.com"
                    ],
                    workerSrc: ["'self'", "blob:"],
                    childSrc: ["'self'", "blob:"],
                    frameSrc: ["'none'"],
                    objectSrc: ["'none'"],
                    baseUri: ["'self'"],
                    formAction: ["'self'"],
                    frameAncestors: ["'none'"]
                }
            }
        }
    }
});

API-Only Server #

const apiServer = createServer({
    security: {
        helmet: {
            contentSecurityPolicy: {
                directives: {
                    defaultSrc: ["'none'"],
                    scriptSrc: ["'none'"],
                    styleSrc: ["'none'"],
                    imgSrc: ["'none'"],
                    fontSrc: ["'none'"],
                    connectSrc: ["'none'"],
                    frameSrc: ["'none'"],
                    objectSrc: ["'none'"],
                    baseUri: ["'none'"],
                    formAction: ["'none'"],
                    frameAncestors: ["'none'"]
                }
            }
        }
    }
});

Development vs Production #

const isProduction = process.env.NODE_ENV === 'production';

const app = createServer({
    security: {
        helmet: {
            contentSecurityPolicy: {
                directives: {
                    defaultSrc: ["'self'"],
                    scriptSrc: isProduction
                        ? ["'self'", "https://cdn.example.com"]
                        : ["'self'", "'unsafe-inline'", "'unsafe-eval'"],
                    styleSrc: isProduction
                        ? ["'self'", "https://fonts.googleapis.com"]
                        : ["'self'", "'unsafe-inline'"],
                    // ... other directives
                }
            }
        }
    }
});

CSP Nonces and Hashes #

Nonce Support #

// Generate nonce for each request
app.use((req, res, next) => {
    res.locals.nonce = crypto.randomBytes(16).toString('base64');
    next();
});

const app = createServer({
    security: {
        helmet: {
            contentSecurityPolicy: {
                directives: {
                    scriptSrc: [
                        "'self'",
                        (req, res) => `'nonce-${res.locals.nonce}'`
                    ]
                }
            }
        }
    }
});

Hash Support #

const app = createServer({
    security: {
        helmet: {
            contentSecurityPolicy: {
                directives: {
                    scriptSrc: [
                        "'self'",
                        "'sha256-abc123...'" // Inline script hash
                    ]
                }
            }
        }
    }
});

Advanced CSP Features #

Report-Only Mode #

const app = createServer({
    security: {
        helmet: {
            contentSecurityPolicy: {
                reportOnly: true, // Don't enforce, just report
                directives: {
                    // Your directives here
                },
                reportUri: "/csp-report"
            }
        }
    }
});

// Handle CSP violation reports
app.post('/csp-report', (req, res) => {
    console.log('CSP Violation:', req.body);
    res.status(204).end();
});

Custom Report URI #

const app = createServer({
    security: {
        helmet: {
            contentSecurityPolicy: {
                directives: {
                    reportUri: "/api/security/csp-violation"
                }
            }
        }
    }
});

CSP Testing and Debugging #

Browser Developer Tools #

Open Developer Tools (F12)
Go to Console tab
Look for CSP violation messages
Check Network tab for blocked resources

Testing Tools #

# Test CSP with curl
curl -H "User-Agent: Mozilla/5.0..." \
     -H "Sec-Fetch-Dest: script" \
     http://localhost:3000

# Check CSP headers
curl -I http://localhost:3000

Common Issues #

Inline Scripts Blocked

// ❌ This will be blocked
<script>console.log('hello');</script>

// ✅ Add 'unsafe-inline' or use nonce/hash
contentSecurityPolicy: {
    directives: {
        scriptSrc: ["'self'", "'unsafe-inline'"]
    }
}

External Resources Blocked

// ❌ This will be blocked
<script src="https://cdn.example.com/script.js"></script>

// ✅ Add domain to CSP
contentSecurityPolicy: {
    directives: {
        scriptSrc: ["'self'", "https://cdn.example.com"]
    }
}

Inline Styles Blocked

// ❌ This will be blocked
<style>body { color: red; }</style>

// ✅ Add 'unsafe-inline' for styles
contentSecurityPolicy: {
    directives: {
        styleSrc: ["'self'", "'unsafe-inline'"]
    }
}

Performance Considerations #

Minimal overhead: CSP headers are static and cached
Browser optimization: Modern browsers optimize CSP parsing
CDN friendly: CSP works well with CDNs and edge networks
Incremental adoption: Start with basic policies and expand gradually

Security Best Practices #

Principle of least privilege: Only allow necessary sources
Avoid 'unsafe-inline': Use nonces or hashes instead
Avoid 'unsafe-eval': Avoid eval() and similar functions
Use HTTPS: Always prefer HTTPS sources
Regular audits: Review and update CSP regularly
Monitor violations: Set up reporting and monitoring
Test thoroughly: Test in all browsers and scenarios

Migration Guide #

From Basic Helmet #

// Before: Basic helmet
const app = createServer({
    security: {
        helmet: true
    }
});

// After: Custom CSP
const app = createServer({
    security: {
        helmet: {
            contentSecurityPolicy: {
                directives: {
                    defaultSrc: ["'self'"],
                    scriptSrc: ["'self'"],
                    styleSrc: ["'self'"]
                }
            }
        }
    }
});

From Express CSP Middleware #

// Before: express-csp
app.use(csp({
    directives: {
        defaultSrc: "'self'",
        scriptSrc: ["'self'", "'unsafe-inline'"]
    }
}));

// After: XyPriss CSP
const app = createServer({
    security: {
        helmet: {
            contentSecurityPolicy: {
                directives: {
                    defaultSrc: ["'self'"],
                    scriptSrc: ["'self'", "'unsafe-inline'"]
                }
            }
        }
    }
});

This enhanced CSP configuration provides developers with complete control over their application's security policies while maintaining ease of use and flexibility.

Contributing to XyPriss features/sys-globals