truelayer/signing

Produce and verify TrueLayer API requests signatures

v1.0.1 2024-12-04 15:48 UTC

Requires

• php: ^8.1
• psr/http-message: ^1.1 | ^2.0
• web-token/jwt-library: ^3.3

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.3
• mockery/mockery: ^1.4
• pestphp/pest: ^1.20
• phpstan/phpstan: ^1.0
• ramsey/uuid: ^4.2
• roave/security-advisories: dev-latest

MIT

• Stefan Adrian Danaita
• Alexandru Lighezan

• signing
• JWS
• truelayer

README

PHP library to produce & verify TrueLayer API request signatures. If you want to know more about how TrueLayer's signatures work, see this documentation for an explanation.

Installation

Require using composer:

$ composer require truelayer/signing

Usage

Signing

First, create a Signer instance, using one of the following methods:

use TrueLayer\Signing\Signer;

$signer = Signer::signWithPemFile('kid-value', '/path/to/privatekey');
$signer = Signer::signWithPem('kid-value', $pemContents);
$signer = Signer::signWithPemBase64('kid-value', $pemContentsBase64Encoded);
$signer = Signer::signWithKey('kid-value', new \Jose\Component\Core\JWK());

Then you can use it to create signatures:

use TrueLayer\Signing\Signer;

$signature = $signer->method('POST')
    ->path('/path') // The api path
    ->header('Idempotency-Key', 'my-key') // The idempotency key you must send with your request
    ->body('stringified request body')
    ->sign();    

You can also sign a PSR-7 request which will automatically compile the signature and add it to the Tl-Signature header.

use TrueLayer\Signing\Signer;

$request = $signer->addSignatureHeader($request)

Verifying

First, retrieve the public keys:

• for sandbox: https://webhooks.truelayer-sandbox.com/.well-known/jwks
• for production: https://webhooks.truelayer.com/.well-known/jwks

Example using the Guzzle library:

use TrueLayer\Signing\Verifier;
use GuzzleHttp\Client;

// Note: you should add error handling as appropriate
$httpClient = new Client();
$response = $httpClient->get('https://webhooks.truelayer-sandbox.com/.well-known/jwks')->getBody()->getContents();
$keys = json_decode($response, true)['keys'];

$verifier = Verifier::verifyWithJsonKeys(...$keys); // Note the spread operator, it's important.

Then you can use it to verify the signature you receive in your webhook under the tl-signature header:

$verifier
    ->path('/path') // Should be your webhook path, for example $_SERVER['REQUEST_URI']
    ->headers($headers) // All headers you receive. Header names can be in any casing.
    ->body('stringified request body'); // For example file_get_contents('php://input');

try {
    $verifier->verify($headers['tl-signature']);
} catch (InvalidSignatureException $e) {
    throw $e; // Handle invalid signature. You should not use this request's data.
}