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.
1a33705de5
indieauth/docs/classes/Taproot-IndieAuth-Storage-TokenStorageInterface.html
Barnaby Walters 02a2773c60 Added phpdoc config, generated documentation
2021-06-12 23:04:51 +02:00

434 lines
24 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;: <a href="classes/Taproot-IndieAuth-Storage-Token.html"><abbr title="\Taproot\IndieAuth\Storage\Token">Token</abbr></a>|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;: <a href="classes/Taproot-IndieAuth-Storage-Token.html"><abbr title="\Taproot\IndieAuth\Storage\Token">Token</abbr></a>|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;: <a href="classes/Taproot-IndieAuth-Storage-Token.html"><abbr title="\Taproot\IndieAuth\Storage\Token">Token</abbr></a>|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">79</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"><a href="classes/Taproot-IndieAuth-Storage-Token.html"><abbr title="\Taproot\IndieAuth\Storage\Token">Token</abbr></a>|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,
and return an instance of <code class="prettyprint">Storage\Token</code> containing both. Implementations will usually add
an expiry time, usually under the <code class="prettyprint">valid_until</code> key.</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"><a href="classes/Taproot-IndieAuth-Storage-Token.html"><abbr title="\Taproot\IndieAuth\Storage\Token">Token</abbr></a>|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">103</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>)</span><span> : </span><span class="phpdocumentor-signature__response_type"><a href="classes/Taproot-IndieAuth-Storage-Token.html"><abbr title="\Taproot\IndieAuth\Storage\Token">Token</abbr></a>|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, returning it in a <code class="prettyprint">Token</code> 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. On an error, the created
access token is immediately revoked via <code class="prettyprint">revokeAccessToken()</code>.</p>
<p>For this reason, the token data in the returned Token object MUST include
the <code class="prettyprint">client_id</code> and <code class="prettyprint">redirect_uri</code> parameters associated with the
authorization code, as these are used by the IndieAuth Server for further
validation.</p>
<p>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.</p>
<p>If the exchanged access token should expire, this method should set its
expiry time, usually in a <code class="prettyprint">valid_until</code> key.</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">
</dd>
</dl>
<h5 class="phpdocumentor-return-value__heading">Return values</h5>
<span class="phpdocumentor-signature__response_type"><a href="classes/Taproot-IndieAuth-Storage-Token.html"><abbr title="\Taproot\IndieAuth\Storage\Token">Token</abbr></a>|null</span>
&mdash;
<section class="phpdocumentor-description"></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">112</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"><a href="classes/Taproot-IndieAuth-Storage-Token.html"><abbr title="\Taproot\IndieAuth\Storage\Token">Token</abbr></a>|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. The data should be structured in
exactly the same way it was stored by <code class="prettyprint">exchangeAuthCodeForAccessToken</code>.</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"><a href="classes/Taproot-IndieAuth-Storage-Token.html"><abbr title="\Taproot\IndieAuth\Storage\Token">Token</abbr></a>|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">120</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