README

Kirby Sign

Kirby Sign makes it easy to generate signed URLs for your Kirby site. These URLs include a secure signature to prevent tampering, ensuring that any shared link is protected from alteration. It’s perfect for confidently sharing public pages or creating temporary links for downloads and sensitive actions.

Installation

Composer

composer require beebmx/kirby-sign

Usage

Kirby Sign comes with two main features: Sign URLs and Validate URLs. But first, you need to create a key to sign your URLs. This key should be placed in your config.php file.

'beebmx.kirby-sign' => [
    'key' => 'your-secret-key',
],

Note

You need to create your own key to sign your URLs. This key can be any string, but it's recommended to use a long and complex string to ensure security. If you need help with it, you can use the console command that Kirby Sign provides to generate a key.

Warning

This key is used to sign your URLs, so it should be kept secret and not shared with anyone.

URLs Signing

You can sign any URL using the Beebmx\KirbySign\Facades\Signed facade. Here's an example of how to sign a URL:

use Beebmx\KirbySign\Facades\Signed;

Signed::url('download/page');

This will return a signed URL that contains a signature to ensure that the URL has not been modified.

Sometimes you may need to sign a URL with additional parameters, such as an id or any other key to identify a user or a transaction, so you can send it with:

use Beebmx\KirbySign\Facades\Signed;

Signed::url('download/page', ['id' => 123, 'transaction' => 'abc']);

Sometimes you may need to expire a signed URL after a certain time, maybe for security reasons or to limit the access to a resource, you can do it by passing the expires option:

use Beebmx\KirbySign\Facades\Signed;
use Carbon\Carbon;

Signed::url(
    'transactional/page', expiration: Carbon::now()->addHour(),
);

In the example above, the signed URL will expire after one hour, and it uses Carbon\Carbon instance, but you can also use a DateInterval instance to set the expiration time.

use Beebmx\KirbySign\Facades\Signed;
use DateInterval;

Signed::url(
    'transactional/page', expiration: DateInterval::createFromDateString('1 hour')
);

By default, all signed URLs will be an absolute URL, but you can also create a relative URL by passing the absolute option as false:

use Beebmx\KirbySign\Facades\Signed;

Signed::url('some/page',  absolute: false);

Page Signing

Kirby Sign also comes with a page method to sign a page URL, this is useful if you want to sign a page URL without having to specify the full path.

$page->signed();

As the same as Signed facade, you can also pass additional parameters to the page method to sign a page URL with additional parameters:

use Carbon\Carbon;

// With additional parameters
$page->signed(['id' => 123]);

// With expiration time
$page->signed(['id' => 123], expiration: Carbon::now()->addHour());

// With relative URL
$page->signed(absolute: false);

URLs Validation

Once you have signed a URL, you can validate it to ensure that it has not been modified and is still valid. A good place to validate a signed URL could be in a controller, but you are free to use it anywhere you need to validate a signed URL.

use Beebmx\KirbySign\Facades\Signed;

return function ($page) {
    if (! Signed::isValid()) {
        go('/', code: 302);
    }
};

If you decide to use a relative URL, you can also validate it by passing the absolute option as false:

use Beebmx\KirbySign\Facades\Signed;

return function ($page) {
    if (! Signed::isValid(absolute: false)) {
        go('/', code: 302);
    }
};

Page Validation

For convenience, Kirby Sign also provides a page method to validate a signed page URL.

return function ($page) {
    // Validate a signed page URL
    if (! $page->hasValidSignature()) {
        go('/', code: 302);
    }

    // Validate a signed page URL with relative URL
    if (! $page->hasValidSignature(absolute: false)) {
        go('/', code: 302);
    }
};

Console

If you are a Kirby CLI user, Kirby Sign comes with a new command to help you create secure keys.

$ kirby key:generate

Note

key:generate command will only generate a random key that you can use to sign your URLs. You can then copy/paste this key in your config.php or environment file as shown in the Usage section.

If you have .env file, you can also use the command to set the key in your file:

$ kirby key:generate --env

Note

The --env option will set the KIRBY_KEY variable in your .env file with the generated key. If no KIRBY_KEY is present in your .env file, it will throw an error.

Helper

For convenience, Kirby Sign provides a helper function to sign URLs and validate them.

// Sign a URL
sign()->url('some/page');

// Validate a URL
sign()->isValid();

In case you don't want to use the global beebmx.kirby-sign.key, you can pass a custom key to the helper function:

// Sign a URL with a custom key
sign('your-custom-key')->url('some/page');

// Validate a URL with a custom key
sign('your-custom-key')->isValid();

Options

Option	Default	Type	Description
beebmx.kirby-sign.key	null	`string`,`null`	Set your own key to create and encrypt your signed or validated URLs.
beebmx.kirby-sign.format	query	`string`	You can set `query` or `params` to adjust the output format of the signed URL.
beebmx.kirby-sign.sign	signature	`string`	You can change the default `signature` parameter to sign or validate any URL.
beebmx.kirby-sign.cipher	AES-256-CBC	`string`	You can change the default algorithm to encrypt the key generation.

Here's an example of a full use of the options from the config.php file:

'beebmx.kirby-sign' => [
    'key' => null,
    'format' => 'query',
    'sign' => 'signature',
    'cipher' => 'AES-256-CBC',
],

License

Licensed under the MIT.

Credits

Kirby Sign is inspired by the Laravel Signed URLs

Fernando Gutierrez @beebmx
Jonas Ceja @jonatanjonas logo
All Contributors

beebmx / kirby-sign

Maintainers

Details

README

Kirby Sign

Overview

Installation

Composer

Usage

URLs Signing

Page Signing

URLs Validation

Page Validation

Console

Helper

Options

License

Credits