mazedlx / laravel-feature-policy
Add Feature-Policy headers to the responses of a Laravel app
Installs: 111 620
Dependents: 0
Suggesters: 0
Security: 0
Stars: 17
Watchers: 4
Forks: 8
Open Issues: 1
Requires
- php: ^8.1|^8.2
- illuminate/http: ^7.0|^8.0|^9.0|^10.0|^11.0
- illuminate/support: ^7.0|^8.0|^9.0|^10.0|^11.0
Requires (Dev)
- driftingly/rector-laravel: ^0.17.0 || ^0.19.0 || ^0.20.0 || ^0.21.0 || ^0.22.0 || ^0.24.0 || ^0.26.0 || ^0.30.0 || ^0.40.0 || ^0.41.0|^1.0
- orchestra/testbench: ^7.0|^8.0|^9.0
- phpunit/phpunit: ^10.0
- rector/rector: ^0.15.21 || ^0.16.0 || ^0.17.0 || ^0.18.0 || ^0.19.0|^1.0
This package is auto-updated.
Last update: 2024-10-27 20:10:45 UTC
README
The Permissions-Policy, which previously was known as the Feature-Policy.
But since it came out of draft, it was renamed to "Permissions-Policy".
The "Permissions-Policy" is an HTTP header which can be used to restrict the abilities of a browser.
Where the Content-Security-Policy focuses on security, the "Permissions-Policy" focuses on allowing or disabling the abilities of the browser.
This can be done though the HTTP header, which this package focuses on, but it can also do this through the allows
attribute on the iframe
element.
iframe example
<iframe width="643" height="360" frameborder="0" allow="autoplay; fullscreen" allowfullscreen></iframe>
More on the header itself can be found on the following sites.
Installation
Laravel 10 users should use v2.0 or newer, otherwise stick to v1.3
The package can be installed though composer:
$ composer require mazedlx/laravel-feature-policy
After which the config file needs to be published:
$ php artisan vendor:publish --provider="Mazedlx\FeaturePolicy\FeaturePolicyServiceProvider" --tag="config"
Which looks like this:
Config file
<?php return [ /* * A policy will determine which "Permissions-Policy" headers will be set. * A valid policy extends `Mazedlx\FeaturePolicy\Policies\Policy` */ 'policy' => Mazedlx\FeaturePolicy\Policies\Basic::class, /* * "Feature-Policy" headers will only be added if this is set to true */ 'enabled' => env('FPH_ENABLED', true), ];
Middleware
You can add "Feature-Policy" headers to all responses by registering Mazedlx\FeaturePolicy\AddFeaturePolicyHeaders::class
in the HTTP kernel:
Middleware example
// app/Http/Kernel.php ... protected $middlewareGroups = [ 'web' => [ ... \Mazedlx\FeaturePolicy\AddFeaturePolicyHeaders::class, ] ];
Alternatively you can add the middleware to a single route and route group:
Route example
// in a routes file use App\Http\Controllers\HomeController; use Mazedlx\FeaturePolicy\AddFeaturePolicyHeaders; Route::get('/home', HomeController::class) ->middleware(AddFeaturePolicyHeaders::class);
You could even pass a policy as a parameter and override the policy specified in the config file:
// in a routes file use App\Http\Controllers\HomeController; use Mazedlx\FeaturePolicy\AddFeaturePolicyHeaders; Route::get('/home', HomeController::class) ->middleware(AddFeaturePolicyHeaders::class . ':' . MyFeaturePolicy::class);
Usage
This package allows you to configure the policies that end up in the "Permissions-Policy" header.
This policy determines which directives will be set in the "Permissions-Policy" header of the response.
It uses the following syntax;
Feature-Policy: <directive> <allowlist>
An example of a "Permissions-Policy" directive is microphone
:
Permissions-Policy: microphone=(self "https://spatie.be")
In the above example by specifying microphone
and allowing it for self
makes the permission disabled for all origins except our own and https://spatie.be.
The current list of directives can be found here. Some of these are:
- accelerometer
- ambient-light-sensor
- autoplay
- camera
- encrypted-media
- fullscreen
- geolocation
- gyroscope
- magnetometer
- microphone
- midi
- payment
- picture-in-picture
- speaker
- usb
- vr
You can add multiple policy options as an array or as a single string with space-separated options:
// in a policy ... ->addDirective(Directive::CAMERA, [ Value::SELF, 'spatie.be', ]) ->addDirective(Directive::GYROSCOPE, 'self spatie.be') ...
Creating Policies
The policy
key of the feature-policy
config file is set to Mazedlx\FeaturePolicy\Policies\Basic::class
by default, which allows your site to use a few of the available features. The class looks like this:
Basic policy
<?php namespace Mazedlx\FeaturePolicy\Policies; use Mazedlx\FeaturePolicy\Value; use Mazedlx\FeaturePolicy\Directive; class Basic extends Policy { public function configure() { $this->addDirective(Directive::GEOLOCATION, Value::SELF) ->addDirective(Directive::FULLSCREEN, Value::SELF); } }
Let's say you're happy with allowing geolocation
and fullscreen
but also wanted to add www.awesomesite.com
to gain access to this feature, then you can easily extend the class:
MyFeature policy
<?php namespace App\Services\FeaturePolicy\Policies; use Mazedlx\FeaturePolicy\Directive; use Mazedlx\FeaturePolicy\Policies\Basic; class MyFeaturePolicy extends Basic { public function configure() { parent::configure(); $this->addDirective(Directive::GEOLOCATION, 'www.awesomesite.com') ->addDirective(Directive::FULLSCREEN, 'www.awesomesite.com'); } }
Don't forget to change the policy
key in the feature-policy
config file to the class name fo your policy (e.g. App\Services\Policies\MyFeaturePolicy
).
Testing
You can run all tests with:
$ composer test
Changelog
Please see CHANGELOG for more information what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Contributers
Made with contrib.rocks.
Security
If you discover any security related issues please email mazedlx@gmail.com instead of using the issue tracker.
Credits
This package is strongly inspired by Spatie laravel-csp package. Thanks to Freek van der Herten and Thomas Verhelst for creating such an awesome package and doing all the heavy lifting!
Support
If you like this package please feel free to star it.
License
The MIT License (MIT). Please see LICENSE for more information.