Preview tokens 8: New structure for preview tokens

[lukasbestle]

Description

Summary of changes & Reasoning

• Use URI instead of ID + template to be able to generate tokens for arbitrary custom blueprint preview URIs
• Include version ID (in a secure way wrapped in JSON) to differentiate preview access by version
• Shorten the token to 10 characters to make the preview URLs more manageable

Additional context

PR 9 will build on the URI-based tokens to implement preview tokens for custom blueprint preview options.

Coverage: One line in the previewTokenFromUrl method is not tested by this PR. This is because this case is prepared for PR 9 and will be tested there.

Changelog

Enhancements

• Preview authentication tokens of drafts and (new in Kirby 5) versions have been shortened to 10 characters to make the preview URLs more manageable.

Breaking changes

• Closures defined for the content.salt option will no longer receive a model when generating a salt for preview authentication tokens of drafts and versions as those tokens are now only based on the URI. Thus the salt callback instead receives null and is expected to return a fixed model-independent salt in this case. When generating a salt for a file media token, the file object is still passed as model.

Docs

Replacing https://getkirby.com/docs/reference/system/options/content#salt-for-drafts-and-media-files:

Salt for page previews and media files

URLs of page previews and media files contain a hashed token that should be hard to guess. The tokens are based on the page URI or file ID and are authenticated with a salt value. In the way Kirby uses this salt value, it should ideally be a secret. By default, Kirby uses the filesystem path of the content folder. You can define your own salt that will be used instead:

return [
  'content' => [
    'salt' => '...'
  ]
];

You can also dynamically generate a salt based on the model that needs a token:

return [
  'content' => [
    'salt' => function ($model) {
      return '...';
    }
  ]
];

<since v="5.0.0">
The $model value is set to the File object when generating a media token for a file. For page preview tokens, $model is always passed as null. Your callback should return a fixed model-independent salt in this case.
</since>

Ready?

• In-code documentation (wherever needed)
• Unit tests for fixed bug/feature
• Tests and CI checks all pass

For review team

• Add lab and/or sandbox examples (wherever helpful)
• Add changes & docs to release notes draft in Notion