diogo/indieauth
Archived
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
This repository has been archived on 2023-08-20. You can view files and clone it, but cannot push or open issues or pull requests.
61aa7f55f9
indieauth/docs/classes/Taproot-IndieAuth-Storage-TokenStorageInterface.html
Barnaby Walters 61aa7f55f9 Refactored TokenStorageInterface for an improved flow 
* Now passing an auth code data validation callback to the exchange method
* Removed Token, it’s no longer necessary
* Simplified interface where possible
* All tests passing
* Updated docblocks
2021-06-13 14:34:37 +02:00

471 lines
25 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<base href="../">
<link rel="icon" href="images/favicon.ico"/>
<link rel="stylesheet" href="css/normalize.css">
<link rel="stylesheet" href="css/base.css">
<link href="https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;600;700&display=swap" rel="stylesheet">
<link rel="stylesheet" href="css/template.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.0/css/all.min.css" integrity="sha256-ybRkN9dBjhcS2qrW1z+hfCxq+1aBdwyQM5wlQoQVt/0=" crossorigin="anonymous" />
<script src="https://cdn.jsdelivr.net/npm/fuse.js@3.4.6"></script>
<script src="https://cdn.jsdelivr.net/npm/css-vars-ponyfill@2"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.0/js/all.min.js" integrity="sha256-0vuk8LXoyrmCjp1f0O300qo1M75ZQyhH9X3J6d+scmk=" crossorigin="anonymous"></script>
<script src="js/search.js"></script>
<script defer src="js/searchIndex.js"></script>
</head>
<body id="top">
<header class="phpdocumentor-header phpdocumentor-section">
<h1 class="phpdocumentor-title"><a href="" class="phpdocumentor-title__link">Documentation</a></h1>
<input class="phpdocumentor-header__menu-button" type="checkbox" id="menu-button" name="menu-button" />
<label class="phpdocumentor-header__menu-icon" for="menu-button">
<i class="fas fa-bars"></i>
</label>
<section data-search-form class="phpdocumentor-search">
<label>
<span class="visually-hidden">Search for</span>
<svg class="phpdocumentor-search__icon" width="21" height="20" viewBox="0 0 21 20" fill="none" xmlns="http://www.w3.org/2000/svg">
<circle cx="7.5" cy="7.5" r="6.5" stroke="currentColor" stroke-width="2"/>
<line x1="12.4892" y1="12.2727" x2="19.1559" y2="18.9393" stroke="currentColor" stroke-width="3"/>
</svg>
<input type="search" class="phpdocumentor-field phpdocumentor-search__field" placeholder="Loading .." disabled />
</label>
</section>
<nav class="phpdocumentor-topnav">
<ul class="phpdocumentor-topnav__menu">
</ul>
</nav>
</header>
<main class="phpdocumentor">
<div class="phpdocumentor-section">
<input class="phpdocumentor-sidebar__menu-button" type="checkbox" id="sidebar-button" name="sidebar-button" />
<label class="phpdocumentor-sidebar__menu-icon" for="sidebar-button">
Menu
</label>
<aside class="phpdocumentor-column -four phpdocumentor-sidebar">
<section class="phpdocumentor-sidebar__category">
<h2 class="phpdocumentor-sidebar__category-header">Namespaces</h2>
<h4 class="phpdocumentor-sidebar__root-namespace"><a href="namespaces/taproot.html"><abbr title="\Taproot">Taproot</abbr></a></h4>
<ul class="phpdocumentor-list">
<li><a href="namespaces/taproot-indieauth.html"><abbr title="\Taproot\IndieAuth">IndieAuth</abbr></a></li>
</ul>
</section>
<section class="phpdocumentor-sidebar__category">
<h2 class="phpdocumentor-sidebar__category-header">Reports</h2>
<h3 class="phpdocumentor-sidebar__root-package"><a href="reports/deprecated.html">Deprecated</a></h3>
<h3 class="phpdocumentor-sidebar__root-package"><a href="reports/errors.html">Errors</a></h3>
<h3 class="phpdocumentor-sidebar__root-package"><a href="reports/markers.html">Markers</a></h3>
</section>
<section class="phpdocumentor-sidebar__category">
<h2 class="phpdocumentor-sidebar__category-header">Indices</h2>
<h3 class="phpdocumentor-sidebar__root-package"><a href="indices/files.html">Files</a></h3>
</section>
</aside>
<div class="phpdocumentor-column -eight phpdocumentor-content">
<ul class="phpdocumentor-breadcrumbs">
<li class="phpdocumentor-breadcrumb"><a href="namespaces/taproot.html">Taproot</a></li>
<li class="phpdocumentor-breadcrumb"><a href="namespaces/taproot-indieauth.html">IndieAuth</a></li>
<li class="phpdocumentor-breadcrumb"><a href="namespaces/taproot-indieauth-storage.html">Storage</a></li>
</ul>
<article class="phpdocumentor-element -interface">
<h2 class="phpdocumentor-content__title">
TokenStorageInterface
</h2>
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/TokenStorageInterface.php"><a href="files/src-storage-tokenstorageinterface.html"><abbr title="src/Storage/TokenStorageInterface.php">TokenStorageInterface.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">37</span>
</aside>
<p class="phpdocumentor-summary">Token Storage Interface</p>
<section class="phpdocumentor-description"><p>This interface defines the bare minimum methods required by the Server class in order to
implement auth code issuing and exchange flows, as well as to let external code get access
tokens (for validating requests authenticated by an access_token) and revoke access tokens.</p>
<p>The contract made between Server and implementations of TokenStorageInterface can broadly
be summarized as follows:</p>
<ul>
<li>The Server class is responsible for performing all validation which is
defined in the IndieAuth spec and is not implementation-specific. For example: checking
validity of all the authorization request parameters, checking that client_id, request_uri
and code_verifier parameters in token exchange requests match with the stored data.</li>
<li>The TokenStorageInterface class is responsible for performing implementation-specific
validation, such as assigning and checking expiry times for auth codes and access tokens.</li>
</ul>
<p>Implementations of TokenStorageInterface will usually implement additional methods to allow
for lower-level querying, saving, updating and deletion of token data. These can be used to,
for example, implement a UI for users to review and revoke currently valid access tokens.</p>
<p>The behaviour of <code class="prettyprint">TokenStorageInterface</code> is somewhat coupled with the implementation of your
authentication handler callback (documented in <code class="prettyprint">Server::__construct</code>) and <code class="prettyprint">AuthorizationFormInterface</code>,
so you should refer to the documentation for both while implementing <code class="prettyprint">TokenStorageInterface</code>.</p>
<p>Periodic deletion of expired tokens is out of the scope of this interface. Implementations may
choose to offer a clean-up method, and potentially the option to call it once automatically
on instantiation.</p>
<p>None of the methods defined on TokenStorageInterface should throw exceptions. Failure, for any
reason, is indicated by returning either <code class="prettyprint">null</code> or <code class="prettyprint">false</code>, depending on the method.</p>
</section>
<h3 id="toc">
Table of Contents
<a href="#toc" class="headerlink"><i class="fas fa-link"></i></a>
</h3>
<dl class="phpdocumentor-table-of-contents">
<dt class="phpdocumentor-table-of-contents__entry -method -public">
<a href="classes/Taproot-IndieAuth-Storage-TokenStorageInterface.html#method_createAuthCode">createAuthCode()</a>
<span>
&nbsp;: string|null </span>
</dt>
<dd>Create Auth Code</dd>
<dt class="phpdocumentor-table-of-contents__entry -method -public">
<a href="classes/Taproot-IndieAuth-Storage-TokenStorageInterface.html#method_exchangeAuthCodeForAccessToken">exchangeAuthCodeForAccessToken()</a>
<span>
&nbsp;: array&lt;string|int, mixed&gt;|null </span>
</dt>
<dd>Exchange Authorization Code for Access Token</dd>
<dt class="phpdocumentor-table-of-contents__entry -method -public">
<a href="classes/Taproot-IndieAuth-Storage-TokenStorageInterface.html#method_getAccessToken">getAccessToken()</a>
<span>
&nbsp;: array&lt;string|int, mixed&gt;|null </span>
</dt>
<dd>Get Access Token</dd>
<dt class="phpdocumentor-table-of-contents__entry -method -public">
<a href="classes/Taproot-IndieAuth-Storage-TokenStorageInterface.html#method_revokeAccessToken">revokeAccessToken()</a>
<span>
&nbsp;: bool </span>
</dt>
<dd>Revoke Access Token</dd>
</dl>
<section class="phpdocumentor-methods">
<h3 class="phpdocumentor-elements__header" id="methods">
Methods
<a href="classes/Taproot-IndieAuth-Storage-TokenStorageInterface.html#methods" class="headerlink"><i class="fas fa-link"></i></a>
</h3>
<article
class="phpdocumentor-element
-method
-public
"
>
<h4 class="phpdocumentor-element__name" id="method_createAuthCode">
createAuthCode()
<a href="classes/Taproot-IndieAuth-Storage-TokenStorageInterface.html#method_createAuthCode" class="headerlink"><i class="fas fa-link"></i></a>
</h4>
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/TokenStorageInterface.php"><a href="files/src-storage-tokenstorageinterface.html"><abbr title="src/Storage/TokenStorageInterface.php">TokenStorageInterface.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">78</span>
</aside>
<p class="phpdocumentor-summary">Create Auth Code</p>
<code class="phpdocumentor-code phpdocumentor-signature ">
<span class="phpdocumentor-signature__visibility">public</span>
<span class="phpdocumentor-signature__name">createAuthCode</span><span>(</span><span class="phpdocumentor-signature__argument"><span class="phpdocumentor-signature__argument__return-type">array&lt;string|int, mixed&gt;&nbsp;</span><span class="phpdocumentor-signature__argument__name">$data</span></span><span>)</span><span> : </span><span class="phpdocumentor-signature__response_type">string|null</span></code>
<section class="phpdocumentor-description"><p>This method is called on a valid authorization token request. The <code class="prettyprint">$data</code>
array is guaranteed to have the following keys:</p>
<ul>
<li>
<code class="prettyprint">client_id</code>: the validated <code class="prettyprint">client_id</code> request parameter</li>
<li>
<code class="prettyprint">redirect_uri</code>: the validated <code class="prettyprint">redirect_uri</code> request parameter</li>
<li>
<code class="prettyprint">state</code>: the <code class="prettyprint">state</code> request parameter</li>
<li>
<code class="prettyprint">code_challenge</code>: the <code class="prettyprint">code_challenge</code> request parameter</li>
<li>
<code class="prettyprint">code_challenge_method</code>: the <code class="prettyprint">code_challenge_method</code> request parameter</li>
<li>
<code class="prettyprint">requested_scope</code>: the value of the <code class="prettyprint">scope</code> request parameter</li>
<li>
<code class="prettyprint">me</code>: the value of the <code class="prettyprint">me</code> key from the authentication result returned from the authentication request handler callback</li>
</ul>
<p>It may also have additional keys, which can come from the following locations:</p>
<ul>
<li>All keys from the the authentication request handler callback result which do not clash
with the keys listed above (with the exception of <code class="prettyprint">me</code>, which is always present). Usually
this is a <code class="prettyprint">profile</code> key, but you may choose to return additional data from the authentication
callback, which will be present in <code class="prettyprint">$data</code>.</li>
<li>Any keys added by the <code class="prettyprint">transformAuthorizationCode</code> method on the currently active instance
of <code class="prettyprint">Taproot\IndieAuth\Callback\AuthorizationFormInterface</code>. Typically this is the <code class="prettyprint">scope</code>
key, which is a valid space-separated scope string listing the scopes granted by the user on
the consent screen. Other implementations of <code class="prettyprint">AuthorizationFormInterface</code> may add additional
data, such as custom token-specific settings, or a custom token lifetime.</li>
</ul>
<p>This method should store the data passed to it, generate a corresponding authorization code
string, and return it.</p>
<p>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.</p>
<p>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.</p>
</section>
<h5 class="phpdocumentor-argument-list__heading">Parameters</h5>
<dl class="phpdocumentor-argument-list">
<dt class="phpdocumentor-argument-list__entry">
<span class="phpdocumentor-signature__argument__name">$data</span>
: <span class="phpdocumentor-signature__argument__return-type">array&lt;string|int, mixed&gt;</span>
</dt>
<dd class="phpdocumentor-argument-list__definition">
</dd>
</dl>
<h5 class="phpdocumentor-return-value__heading">Return values</h5>
<span class="phpdocumentor-signature__response_type">string|null</span>
&mdash;
<section class="phpdocumentor-description"></section>
</article>
<article
class="phpdocumentor-element
-method
-public
"
>
<h4 class="phpdocumentor-element__name" id="method_exchangeAuthCodeForAccessToken">
exchangeAuthCodeForAccessToken()
<a href="classes/Taproot-IndieAuth-Storage-TokenStorageInterface.html#method_exchangeAuthCodeForAccessToken" class="headerlink"><i class="fas fa-link"></i></a>
</h4>
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/TokenStorageInterface.php"><a href="files/src-storage-tokenstorageinterface.html"><abbr title="src/Storage/TokenStorageInterface.php">TokenStorageInterface.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">119</span>
</aside>
<p class="phpdocumentor-summary">Exchange Authorization Code for Access Token</p>
<code class="phpdocumentor-code phpdocumentor-signature ">
<span class="phpdocumentor-signature__visibility">public</span>
<span class="phpdocumentor-signature__name">exchangeAuthCodeForAccessToken</span><span>(</span><span class="phpdocumentor-signature__argument"><span class="phpdocumentor-signature__argument__return-type">string&nbsp;</span><span class="phpdocumentor-signature__argument__name">$code</span></span><span class="phpdocumentor-signature__argument"><span>, </span><span class="phpdocumentor-signature__argument__return-type">callable&nbsp;</span><span class="phpdocumentor-signature__argument__name">$validateAuthCode</span></span><span>)</span><span> : </span><span class="phpdocumentor-signature__response_type">array&lt;string|int, mixed&gt;|null</span></code>
<section class="phpdocumentor-description"><p>Attempt to exchange an authorization code identified by <code class="prettyprint">$code</code> for
an access token. Return an array of access token data to be passed onto
the client app on success, and null on error.</p>
<p>This method is called at the beginning of a code exchange request, before
further error checking or validation is applied. It should proceed as
follows.</p>
<ul>
<li>Attempt to fetch the authorization code data identified by $code. If
it does not exist or has expired, return null;</li>
<li>Pass the authorization code data array to $validateAuthCode for validation.
If there is a problem with the code, a <code class="prettyprint">Taproot\IndieAuth\IndieAuthException</code>
will be thrown. This method should catch it, invalidate the authorization
code data, then re-throw the exception for handling by Server.</li>
<li>If the authorization code data passed all checks, convert it into an access
token, invalidate the auth code to prevent re-use, and store the access token
data internally.</li>
<li>Return an array of access token data to be passed onto the client app. It MUST
contain the following keys:
<ul>
<li>
<code class="prettyprint">me</code>
</li>
<li>
<code class="prettyprint">access_token</code>
Additonally, it SHOULD contain the following keys:</li>
<li>
<code class="prettyprint">scope</code>, if the token grants any scope
And MAY contain additional keys, such as:</li>
<li>
<code class="prettyprint">profile</code>
</li>
<li>
<code class="prettyprint">expires_at</code>
</li>
</ul>
</li>
</ul>
<p>If the authorization code was redeemed at the authorization endpoint, Server will
only pass the <code class="prettyprint">me</code> and <code class="prettyprint">profile</code> keys onto the client. In both cases, it will filter
out <code class="prettyprint">code_challenge</code> keys to prevent that data from accidentally being leaked to
clients.</p>
</section>
<h5 class="phpdocumentor-argument-list__heading">Parameters</h5>
<dl class="phpdocumentor-argument-list">
<dt class="phpdocumentor-argument-list__entry">
<span class="phpdocumentor-signature__argument__name">$code</span>
: <span class="phpdocumentor-signature__argument__return-type">string</span>
</dt>
<dd class="phpdocumentor-argument-list__definition">
<section class="phpdocumentor-description"><p>The Authorization Code to attempt to exchange.</p>
</section>
</dd>
<dt class="phpdocumentor-argument-list__entry">
<span class="phpdocumentor-signature__argument__name">$validateAuthCode</span>
: <span class="phpdocumentor-signature__argument__return-type">callable</span>
</dt>
<dd class="phpdocumentor-argument-list__definition">
<section class="phpdocumentor-description"><p>A callable to perform additional validation if valid auth code data is found. Takes <code class="prettyprint">array $authCodeData</code>, raises <code class="prettyprint">Taproot\IndieAuth\IndieAuthException</code> on invalid data, which should be bubbled up to the caller after any clean-up. Returns void.</p>
</section>
</dd>
</dl>
<h5 class="phpdocumentor-return-value__heading">Return values</h5>
<span class="phpdocumentor-signature__response_type">array&lt;string|int, mixed&gt;|null</span>
&mdash;
<section class="phpdocumentor-description"><p>An array of access token data to return to the client on success, null on any error.</p>
</section>
</article>
<article
class="phpdocumentor-element
-method
-public
"
>
<h4 class="phpdocumentor-element__name" id="method_getAccessToken">
getAccessToken()
<a href="classes/Taproot-IndieAuth-Storage-TokenStorageInterface.html#method_getAccessToken" class="headerlink"><i class="fas fa-link"></i></a>
</h4>
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/TokenStorageInterface.php"><a href="files/src-storage-tokenstorageinterface.html"><abbr title="src/Storage/TokenStorageInterface.php">TokenStorageInterface.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">127</span>
</aside>
<p class="phpdocumentor-summary">Get Access Token</p>
<code class="phpdocumentor-code phpdocumentor-signature ">
<span class="phpdocumentor-signature__visibility">public</span>
<span class="phpdocumentor-signature__name">getAccessToken</span><span>(</span><span class="phpdocumentor-signature__argument"><span class="phpdocumentor-signature__argument__return-type">string&nbsp;</span><span class="phpdocumentor-signature__argument__name">$token</span></span><span>)</span><span> : </span><span class="phpdocumentor-signature__response_type">array&lt;string|int, mixed&gt;|null</span></code>
<section class="phpdocumentor-description"><p>Fetch access token data identified by the token <code class="prettyprint">$token</code>, returning
null if it is expired or invalid.</p>
</section>
<h5 class="phpdocumentor-argument-list__heading">Parameters</h5>
<dl class="phpdocumentor-argument-list">
<dt class="phpdocumentor-argument-list__entry">
<span class="phpdocumentor-signature__argument__name">$token</span>
: <span class="phpdocumentor-signature__argument__return-type">string</span>
</dt>
<dd class="phpdocumentor-argument-list__definition">
</dd>
</dl>
<h5 class="phpdocumentor-return-value__heading">Return values</h5>
<span class="phpdocumentor-signature__response_type">array&lt;string|int, mixed&gt;|null</span>
&mdash;
<section class="phpdocumentor-description"></section>
</article>
<article
class="phpdocumentor-element
-method
-public
"
>
<h4 class="phpdocumentor-element__name" id="method_revokeAccessToken">
revokeAccessToken()
<a href="classes/Taproot-IndieAuth-Storage-TokenStorageInterface.html#method_revokeAccessToken" class="headerlink"><i class="fas fa-link"></i></a>
</h4>
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/TokenStorageInterface.php"><a href="files/src-storage-tokenstorageinterface.html"><abbr title="src/Storage/TokenStorageInterface.php">TokenStorageInterface.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">135</span>
</aside>
<p class="phpdocumentor-summary">Revoke Access Token</p>
<code class="phpdocumentor-code phpdocumentor-signature ">
<span class="phpdocumentor-signature__visibility">public</span>
<span class="phpdocumentor-signature__name">revokeAccessToken</span><span>(</span><span class="phpdocumentor-signature__argument"><span class="phpdocumentor-signature__argument__return-type">string&nbsp;</span><span class="phpdocumentor-signature__argument__name">$token</span></span><span>)</span><span> : </span><span class="phpdocumentor-signature__response_type">bool</span></code>
<section class="phpdocumentor-description"><p>Revoke the access token identified by <code class="prettyprint">$token</code>. Return true on success,
or false on error, including if the token did not exist.</p>
</section>
<h5 class="phpdocumentor-argument-list__heading">Parameters</h5>
<dl class="phpdocumentor-argument-list">
<dt class="phpdocumentor-argument-list__entry">
<span class="phpdocumentor-signature__argument__name">$token</span>
: <span class="phpdocumentor-signature__argument__return-type">string</span>
</dt>
<dd class="phpdocumentor-argument-list__definition">
</dd>
</dl>
<h5 class="phpdocumentor-return-value__heading">Return values</h5>
<span class="phpdocumentor-signature__response_type">bool</span>
&mdash;
<section class="phpdocumentor-description"></section>
</article>
</section>
</article>
<section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden">
<section class="phpdocumentor-search-results__dialog">
<header class="phpdocumentor-search-results__header">
<h2 class="phpdocumentor-search-results__title">Search results</h2>
<button class="phpdocumentor-search-results__close"><i class="fas fa-times"></i></button>
</header>
<section class="phpdocumentor-search-results__body">
<ul class="phpdocumentor-search-results__entries"></ul>
</section>
</section>
</section>
</div>
</div>
<a href="classes/Taproot-IndieAuth-Storage-TokenStorageInterface.html#top" class="phpdocumentor-back-to-top"><i class="fas fa-chevron-circle-up"></i></a>
</main>
<script>
cssVars({});
</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink