decodelabs/cipher

Tools and systems to interact with JWTs

v0.1.3 2024-08-22 02:55 UTC

This package is auto-updated.

Last update: 2024-11-04 21:22:35 UTC


README

PHP from Packagist Latest Version Total Downloads GitHub Workflow Status PHPStan License

Tools and systems to interact with JWTs

Cipher provides an integrated suite of tools for working with JWTs, including a simple interface for creating and verifying tokens, and a set of middleware for use with Harvest, Greenleaf, or any other PSR-15 compatible middleware stack.

Get news and updates on the DecodeLabs blog.

Installation

Install via Composer:

composer require decodelabs/cipher

Usage

### Codec

The Codec class provides the means to encode and decode JWTs. The class requires an instance of DecodeLabs\Cipher\Config to be passed to the constructor - we provide a default Dovetail implementation for this, but you can use your own if you wish.

The config defines what secret and algorithm is used.

use DecodeLabs\Cipher\Codec;
use DecodeLabs\Dovetail;

$codec = new Codec(
    Dovetail::load('Cipher')
);

$payload = $codec->decode($token);

Payload

The Payload interface defines a simple wrapper around JWT payload data with ArrayAccess support. The Factory will instantiate a Generic payload for unrecognized issuers, however extended implementations for specific issuers can be created and used instead, providing formal access to custom claim data.

// $payload['iss'] = 'https://abcdefg.supabase.co/auth/v1'
// $payload instance of DecodeLabs\Cipher\Payload\Supabase
$email = $payload->getEmail();
$provider = $payload->getProvider();

Middleware

Cipher provides a set of middleware for use with Harvest or Greenleaf, or any other PSR-15 compatible middleware stack.

With the Middleware in your PSR-15 stack, Cipher will attempt to load a JWT from the request, and if successful, will set the jwt.payload attribute on the request with the decoded payload.

$payload = $request->getAttribute('jwt.payload');

If using Greenleaf, the payload can be injected into your action automatically via Slingshot, (below example uses Supabase payload):

use DecodeLabs\Cipher\Payload\Supabase;
use DecodeLabs\Greenleaf\Action;
use DecodeLabs\Greenleaf\Action\ByMethodTrait;
use DecodeLabs\Harvest;
use DecodeLabs\Harvest\Response;

class MySecureAction implements Action
{
    use ByMethodTrait;

    public const Middleware = [
        'Jwt' => [
            'required' => true
        ]
    ];

    public function get(
        Supabase $payload
    ): Response {
        return Harvest::json([
            'email' => $payload->getEmail()
        ]);
    }
}

Licensing

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