README

Content Security Policies for your PHP application.

Sanctum allows you to create and deploy Content Security Policies with ease. Take the guesswork out of this important security feature.

Installation

This package requires PHP 8.4 or higher.

Install via Composer:

composer require decodelabs/sanctum

Usage

Create your definition:

use DecodeLabs\Sanctum\Definition;

class MyCsp extends Definition {

    // These items can be reused in other directives
    const SharedSrc = [
        '@self', // Resolves to 'self'
        '*.myotherdomain.com'
    ];

    // These items create the default-src directive
    const DefaultSrc = [
        '@shared-src', // Import items from SharedSrc
    ];

    // These define script sources
    const ScriptSrc = [
        '@nonce', // Creates a unique nonce to be used in markup
        '@unsafe-inline', // Resolves to 'unsafe-inline'

        '@strict-dynamic',
        '@https',
        '@http'
    ];

    // These define image sources
    const ImgSrc = [
        '@shared', // Import items from SharedSrc
        '@data', // Resolves to data: for data URLs
        '*.myimagecdn.net',
        '!*.myotherdomain.com' // Exclude importing from SharedSrc
    ];


    // Report endpoint
    const ReportUri = 'https://mydomain.com/report';
}

Please see https://content-security-policy.com/ for a full list of directives.

Then in your HTTP handler:

$csp = new MyCsp();

foreach($csp->exportHeaders() as $header => $value) {
    $response->setHeader($header, $value);
}

/*
Reporting-Endpoints => sanctum-csp-report="https://mydomain.com/report"
Content-Security-Policy =>
    default-src 'self' *.myotherdomain.com;
    script-src nonce-98b88fa48f23911d6fc1f5092efb2e36d76423ce4f5d7ef42765a2c2501d57c9' 'unsafe-inline' 'strict-dynamic' https: http:;
    img-src 'self' data: *.myimagecdn.net;
    report-uri https://mydomain.com/report;
    report-to sanctum-csp-report
*/

Hashes

Make use of the hash feature for scripts - see https://content-security-policy.com/hash/ for explanation

/*
HTML:
<script>doSomething();</script>
*/
$script = 'doSomething();'; // Your JS


// Adds sha256-xxx hash to CSP directive
$hash = $csp->hashContent($script, 'script-src');

Archetype loader

Sanctum also provides an optional Archetype loader:

namespace DecodeLabs\Sanctum\Definition;

use DecodeLabs\Sanctum\Definition;

class MyCsp extends Definition {}

$csp = Definition::load('MyCsp');
$csp->exportHeaders();

Archetype will look for implementations in the root namespace (DecodeLabs\Sanctum\Definition) by default. If you want to host your implementations in a different namespace, you should create and register a new Archetype resolver to find them.

Licensing

Sanctum is licensed under the MIT License. See LICENSE for the full license text.