README

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.

Installation

This package requires PHP 8.4 or higher.

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;
use DecodeLabs\Monarch;

$dovetail = Monarch::getService(Dovetail::class);
$config = $dovetail->load('Cipher');
$codec = new Codec($config);

$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\Response\Json as JsonResponse;

class MySecureAction implements Action
{
    use ByMethodTrait;

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

    public function get(
        Supabase $payload,
    ): JsonResponse {
        return new JsonResponse([
            'email' => $payload->getEmail()
        ]);
    }
}

Licensing

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