Documentation

FilesystemJsonStorage implements TokenStorageInterface, LoggerAwareInterface

Filesystem JSON Token Storage

An implementation of TokenStorageInterface which stores authorization codes and access tokens in the filesystem as JSON files, and supports custom access token lifetimes.

This is intended as a default, example implementation with minimal requirements. In practise, most people should probably be using an SQLite3 version of this which I haven’t written yet. I haven’t extensively documented this class, as it will likely be superceded by the SQLite version.

Interfaces, Classes and Traits

TokenStorageInterface
Token Storage Interface
LoggerAwareInterface

Table of Contents

DEFAULT_ACCESS_TOKEN_TTL  = 60 * 60 * 24 * 7
DEFAULT_AUTH_CODE_TTL  = 60 * 5
TOKEN_LENGTH  = 64
$accessTokenTtl  : int
$authCodeTtl  : int
$logger  : LoggerInterface
$path  : string
$secret  : string
__construct()  : mixed
createAuthCode()  : Token|null
Create Auth Code
delete()  : bool
deleteExpiredTokens()  : int
exchangeAuthCodeForAccessToken()  : Token|null
Exchange Authorization Code for Access Token
get()  : array<string|int, mixed>|null
getAccessToken()  : Token|null
Get Access Token
getPath()  : string
put()  : bool
revokeAccessToken()  : bool
Revoke Access Token
setLogger()  : mixed
hash()  : string
withLock()  : mixed

Constants

Properties

Methods

__construct()

public __construct(string $path, string $secret[, int|null $authCodeTtl = null ][, int|null $accessTokenTtl = null ][, mixed $cleanUpNow = false ][, LoggerInterface|null $logger = null ]) : mixed
Parameters
$path : string
$secret : string
$authCodeTtl : int|null = null
$accessTokenTtl : int|null = null
$cleanUpNow : mixed = false
$logger : LoggerInterface|null = null
Return values
mixed —

createAuthCode()

Create Auth Code

public createAuthCode(array<string|int, mixed> $data) : Token|null

This method is called on a valid authorization token request. The $data array is guaranteed to have the following keys:

  • client_id: the validated client_id request parameter
  • redirect_uri: the validated redirect_uri request parameter
  • state: the state request parameter
  • code_challenge: the code_challenge request parameter
  • code_challenge_method: the code_challenge_method request parameter
  • requested_scope: the value of the scope request parameter
  • me: the value of the me key from the authentication result returned from the authentication request handler callback

It may also have additional keys, which can come from the following locations:

  • All keys from the the authentication request handler callback result which do not clash with the keys listed above (with the exception of me, which is always present). Usually this is a profile key, but you may choose to return additional data from the authentication callback, which will be present in $data.
  • Any keys added by the transformAuthorizationCode method on the currently active instance of Taproot\IndieAuth\Callback\AuthorizationFormInterface. Typically this is the scope key, which is a valid space-separated scope string listing the scopes granted by the user on the consent screen. Other implementations of AuthorizationFormInterface may add additional data, such as custom token-specific settings, or a custom token lifetime.

This method should store the data passed to it, generate a corresponding authorization code, and return an instance of Storage\Token containing both. Implementations will usually add an expiry time, usually under the valid_until key.

The method call and data is structured such that implementations have a lot of flexibility about how to store authorization code data. It could be a record in an auth code database table, a record in a table which is used for both auth codes and access tokens, or even a stateless self-encrypted token — note that in the latter case, you must persist a copy of the auth code with its exchanged access token to check against, in order to prevent it being exchanged more than once.

On an error, return null. The reason for the error is irrelevant for calling code, but it’s recommended to log it internally for reference. For the same reason, this method should not throw exceptions.

Parameters
$data : array<string|int, mixed>
Return values
Token|null —

delete()

public delete(string $key) : bool
Parameters
$key : string
Return values
bool —

exchangeAuthCodeForAccessToken()

Exchange Authorization Code for Access Token

public exchangeAuthCodeForAccessToken(string $code) : Token|null

Attempt to exchange an authorization code identified by $code for an access token, returning it in a Token on success and null on error.

This method is called at the beginning of a code exchange request, before further error checking or validation is applied. On an error, the created access token is immediately revoked via revokeAccessToken().

For this reason, the token data in the returned Token object MUST include the client_id and redirect_uri parameters associated with the authorization code, as these are used by the IndieAuth Server for further validation.

This method is responsible for ensuring that the matched auth code is not expired. If it is, it should return null, presumably after deleting the corresponding authorization code record.

If the exchanged access token should expire, this method should set its expiry time, usually in a valid_until key.

Parameters
$code : string
Return values
Token|null —

get()

public get(string $key) : array<string|int, mixed>|null
Parameters
$key : string
Return values
array<string|int, mixed>|null —

getAccessToken()

Get Access Token

public getAccessToken(string $token) : Token|null

Fetch access token data identified by the token $token, returning null if it is expired or invalid. The data should be structured in exactly the same way it was stored by exchangeAuthCodeForAccessToken.

Parameters
$token : string
Return values
Token|null —

getPath()

public getPath(string $key) : string
Parameters
$key : string
Return values
string —

put()

public put(string $key, array<string|int, mixed> $data) : bool
Parameters
$key : string
$data : array<string|int, mixed>
Return values
bool —

revokeAccessToken()

Revoke Access Token

public revokeAccessToken(string $token) : bool

Revoke the access token identified by $token. Return true on success, or false on error, including if the token did not exist.

Parameters
$token : string
Return values
bool —

setLogger()

public setLogger(LoggerInterface $logger) : mixed
Parameters
$logger : LoggerInterface
Return values
mixed —

hash()

protected hash(string $token) : string
Parameters
$token : string
Return values
string —

withLock()

protected withLock(string $path, string $mode, callable $callback) : mixed
Parameters
$path : string
$mode : string
$callback : callable
Return values
mixed —

Search results