Added a bunch of extra documentation

This commit is contained in:
Barnaby Walters 2021-06-13 00:01:32 +02:00
parent 9234ad64bd
commit 62d02dacc0
12 changed files with 212 additions and 73 deletions

View File

@ -93,10 +93,24 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/DefaultAuthorizationForm.php"><a href="files/src-callback-defaultauthorizationform.html"><abbr title="src/Callback/DefaultAuthorizationForm.php">DefaultAuthorizationForm.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">15</span>
<span class="phpdocumentor-element-found-in__line">35</span>
</aside>
<p class="phpdocumentor-summary">Default Authorization Form</p>
<section class="phpdocumentor-description"><p>This implementation of <code class="prettyprint">AuthorizationFormInterface</code> is used by <code class="prettyprint">Server</code> if the user doesnt
provide one of their own. It presents the user with a simple consent screen, showing any
available details about the client app, and allowing the user to grant any requested scopes.</p>
<p>When the form is submitted, any granted scopes are then added to the authorization code data.</p>
<p>You can customise the authorization template used by passing a path to your own template to
the constructor. Refer to the default template <code class="prettyprint">/templates/default_authorization_page.html.php</code>
as a starting point.</p>
<p>If you want to add additional form controls (e.g. configurable token lifetimes), as well as
making a new template, youll need to make a subclass which overrides <code class="prettyprint">transformAuthorizationCode()</code>
to additionally handle your new form data.</p>
<p>For any more involved customisation (for example using a templating library of your choice), it
may make sense to create your own implementation of <code class="prettyprint">AuthorizationFormInterface</code>.</p>
</section>
@ -150,7 +164,7 @@
<span>
&nbsp;: mixed </span>
</dt>
<dd></dd>
<dd>Constructor</dd>
<dt class="phpdocumentor-table-of-contents__entry -method -public">
<a href="classes/Taproot-IndieAuth-Callback-DefaultAuthorizationForm.html#method_setLogger">setLogger()</a>
@ -201,7 +215,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/DefaultAuthorizationForm.php"><a href="files/src-callback-defaultauthorizationform.html"><abbr title="src/Callback/DefaultAuthorizationForm.php">DefaultAuthorizationForm.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">16</span>
<span class="phpdocumentor-element-found-in__line">36</span>
</aside>
@ -231,7 +245,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/DefaultAuthorizationForm.php"><a href="files/src-callback-defaultauthorizationform.html"><abbr title="src/Callback/DefaultAuthorizationForm.php">DefaultAuthorizationForm.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">18</span>
<span class="phpdocumentor-element-found-in__line">38</span>
</aside>
@ -261,7 +275,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/DefaultAuthorizationForm.php"><a href="files/src-callback-defaultauthorizationform.html"><abbr title="src/Callback/DefaultAuthorizationForm.php">DefaultAuthorizationForm.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">20</span>
<span class="phpdocumentor-element-found-in__line">40</span>
</aside>
@ -295,14 +309,16 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/DefaultAuthorizationForm.php"><a href="files/src-callback-defaultauthorizationform.html"><abbr title="src/Callback/DefaultAuthorizationForm.php">DefaultAuthorizationForm.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">22</span>
<span class="phpdocumentor-element-found-in__line">49</span>
</aside>
<p class="phpdocumentor-summary">Constructor</p>
<code class="phpdocumentor-code phpdocumentor-signature ">
<span class="phpdocumentor-signature__visibility">public</span>
<span class="phpdocumentor-signature__name">__construct</span><span>(</span><span class="phpdocumentor-signature__argument"><span>[</span><span class="phpdocumentor-signature__argument__return-type">string|null&nbsp;</span><span class="phpdocumentor-signature__argument__name">$formTemplatePath</span><span> = </span><span class="phpdocumentor-signature__argument__default-value">null</span><span> ]</span></span><span class="phpdocumentor-signature__argument"><span>[</span><span>, </span><span class="phpdocumentor-signature__argument__return-type">string|null&nbsp;</span><span class="phpdocumentor-signature__argument__name">$csrfKey</span><span> = </span><span class="phpdocumentor-signature__argument__default-value">null</span><span> ]</span></span><span class="phpdocumentor-signature__argument"><span>[</span><span>, </span><span class="phpdocumentor-signature__argument__return-type"><abbr title="\Psr\Log\LoggerInterface">LoggerInterface</abbr>|null&nbsp;</span><span class="phpdocumentor-signature__argument__name">$logger</span><span> = </span><span class="phpdocumentor-signature__argument__default-value">null</span><span> ]</span></span><span>)</span><span> : </span><span class="phpdocumentor-signature__response_type">mixed</span></code>
<section class="phpdocumentor-description"></section>
<h5 class="phpdocumentor-argument-list__heading">Parameters</h5>
<dl class="phpdocumentor-argument-list">
@ -311,6 +327,8 @@
: <span class="phpdocumentor-signature__argument__return-type">string|null</span>
= <span class="phpdocumentor-signature__argument__default-value">null</span> </dt>
<dd class="phpdocumentor-argument-list__definition">
<section class="phpdocumentor-description"><p>The path to a custom template. Uses the default if null.</p>
</section>
</dd>
<dt class="phpdocumentor-argument-list__entry">
@ -318,6 +336,8 @@
: <span class="phpdocumentor-signature__argument__return-type">string|null</span>
= <span class="phpdocumentor-signature__argument__default-value">null</span> </dt>
<dd class="phpdocumentor-argument-list__definition">
<section class="phpdocumentor-description"><p>The key used to retrieve a CSRF token from the request attributes, and as its form data name. Uses the default defined in Server if null. Only change this if youre using a custom CSRF middleware.</p>
</section>
</dd>
<dt class="phpdocumentor-argument-list__entry">
@ -325,6 +345,8 @@
: <span class="phpdocumentor-signature__argument__return-type"><abbr title="\Psr\Log\LoggerInterface">LoggerInterface</abbr>|null</span>
= <span class="phpdocumentor-signature__argument__default-value">null</span> </dt>
<dd class="phpdocumentor-argument-list__definition">
<section class="phpdocumentor-description"><p>A logger.</p>
</section>
</dd>
</dl>
@ -351,7 +373,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/DefaultAuthorizationForm.php"><a href="files/src-callback-defaultauthorizationform.html"><abbr title="src/Callback/DefaultAuthorizationForm.php">DefaultAuthorizationForm.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">75</span>
<span class="phpdocumentor-element-found-in__line">102</span>
</aside>
@ -393,7 +415,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/DefaultAuthorizationForm.php"><a href="files/src-callback-defaultauthorizationform.html"><abbr title="src/Callback/DefaultAuthorizationForm.php">DefaultAuthorizationForm.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">28</span>
<span class="phpdocumentor-element-found-in__line">55</span>
</aside>
<p class="phpdocumentor-summary">Show Form</p>
@ -499,7 +521,7 @@ library, but, if stored on the access token, will be available to your app for u
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/DefaultAuthorizationForm.php"><a href="files/src-callback-defaultauthorizationform.html"><abbr title="src/Callback/DefaultAuthorizationForm.php">DefaultAuthorizationForm.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">61</span>
<span class="phpdocumentor-element-found-in__line">88</span>
</aside>
<p class="phpdocumentor-summary">Transform Authorization Code</p>

View File

@ -90,12 +90,36 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/SingleUserPasswordAuthenticationCallback.php"><a href="files/src-callback-singleuserpasswordauthenticationcallback.html"><abbr title="src/Callback/SingleUserPasswordAuthenticationCallback.php">SingleUserPasswordAuthenticationCallback.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">16</span>
<span class="phpdocumentor-element-found-in__line">43</span>
</aside>
<p class="phpdocumentor-summary">Single User Password Authentication Callback</p>
<section class="phpdocumentor-description"></section>
<section class="phpdocumentor-description"><p>A simple example authentication callback which performs authentication itself rather
than redirecting to an existing authentication flow.</p>
<p>In some cases, it may make sense for your IndieAuth server to be able to authenticate
users itself, rather than redirecting them to an existing authentication flow. This
implementation provides a simple single-user password authentication method intended
for bootstrapping and testing purposes.</p>
<p>The sign-in form can be customised by making your own template and passing the path to
the constructor.</p>
<p>Minimal usage:</p>
<pre class="prettyprint"><code class="prettyprint">// One-off during app configuration:
YOUR_HASHED_PASSWORD = password_hash('my super strong password', PASSWORD_DEFAULT);
// In your app:
use Taproot\IndieAuth;
$server = new IndieAuth\Server([
'handleAuthenticationRequestCallback' =&gt; new IndieAuth\Callback\SingleUserPasswordAuthenticationCallback(
['me' =&gt; 'https://me.example.com/'],
YOUR_HASHED_PASSWORD
)
]);
</code></pre>
<p>See documentation for <code class="prettyprint">__construct()</code> for information about customising behaviour.</p>
</section>
@ -150,7 +174,7 @@
<span>
&nbsp;: mixed </span>
</dt>
<dd></dd>
<dd>Constructor</dd>
<dt class="phpdocumentor-table-of-contents__entry -method -public">
<a href="classes/Taproot-IndieAuth-Callback-SingleUserPasswordAuthenticationCallback.html#method___invoke">__invoke()</a>
@ -178,7 +202,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/SingleUserPasswordAuthenticationCallback.php"><a href="files/src-callback-singleuserpasswordauthenticationcallback.html"><abbr title="src/Callback/SingleUserPasswordAuthenticationCallback.php">SingleUserPasswordAuthenticationCallback.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">17</span>
<span class="phpdocumentor-element-found-in__line">44</span>
</aside>
@ -218,7 +242,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/SingleUserPasswordAuthenticationCallback.php"><a href="files/src-callback-singleuserpasswordauthenticationcallback.html"><abbr title="src/Callback/SingleUserPasswordAuthenticationCallback.php">SingleUserPasswordAuthenticationCallback.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">19</span>
<span class="phpdocumentor-element-found-in__line">46</span>
</aside>
@ -248,7 +272,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/SingleUserPasswordAuthenticationCallback.php"><a href="files/src-callback-singleuserpasswordauthenticationcallback.html"><abbr title="src/Callback/SingleUserPasswordAuthenticationCallback.php">SingleUserPasswordAuthenticationCallback.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">20</span>
<span class="phpdocumentor-element-found-in__line">47</span>
</aside>
@ -278,7 +302,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/SingleUserPasswordAuthenticationCallback.php"><a href="files/src-callback-singleuserpasswordauthenticationcallback.html"><abbr title="src/Callback/SingleUserPasswordAuthenticationCallback.php">SingleUserPasswordAuthenticationCallback.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">22</span>
<span class="phpdocumentor-element-found-in__line">49</span>
</aside>
@ -308,7 +332,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/SingleUserPasswordAuthenticationCallback.php"><a href="files/src-callback-singleuserpasswordauthenticationcallback.html"><abbr title="src/Callback/SingleUserPasswordAuthenticationCallback.php">SingleUserPasswordAuthenticationCallback.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">21</span>
<span class="phpdocumentor-element-found-in__line">48</span>
</aside>
@ -342,14 +366,16 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/SingleUserPasswordAuthenticationCallback.php"><a href="files/src-callback-singleuserpasswordauthenticationcallback.html"><abbr title="src/Callback/SingleUserPasswordAuthenticationCallback.php">SingleUserPasswordAuthenticationCallback.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">24</span>
<span class="phpdocumentor-element-found-in__line">59</span>
</aside>
<p class="phpdocumentor-summary">Constructor</p>
<code class="phpdocumentor-code phpdocumentor-signature ">
<span class="phpdocumentor-signature__visibility">public</span>
<span class="phpdocumentor-signature__name">__construct</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">$user</span></span><span class="phpdocumentor-signature__argument"><span>, </span><span class="phpdocumentor-signature__argument__return-type">string&nbsp;</span><span class="phpdocumentor-signature__argument__name">$hashedPassword</span></span><span class="phpdocumentor-signature__argument"><span>[</span><span>, </span><span class="phpdocumentor-signature__argument__return-type">string|null&nbsp;</span><span class="phpdocumentor-signature__argument__name">$csrfKey</span><span> = </span><span class="phpdocumentor-signature__argument__default-value">null</span><span> ]</span></span><span class="phpdocumentor-signature__argument"><span>[</span><span>, </span><span class="phpdocumentor-signature__argument__return-type">string|null&nbsp;</span><span class="phpdocumentor-signature__argument__name">$formTemplate</span><span> = </span><span class="phpdocumentor-signature__argument__default-value">null</span><span> ]</span></span><span>)</span><span> : </span><span class="phpdocumentor-signature__response_type">mixed</span></code>
<span class="phpdocumentor-signature__name">__construct</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">$user</span></span><span class="phpdocumentor-signature__argument"><span>, </span><span class="phpdocumentor-signature__argument__return-type">string&nbsp;</span><span class="phpdocumentor-signature__argument__name">$hashedPassword</span></span><span class="phpdocumentor-signature__argument"><span>[</span><span>, </span><span class="phpdocumentor-signature__argument__return-type">string|null&nbsp;</span><span class="phpdocumentor-signature__argument__name">$formTemplate</span><span> = </span><span class="phpdocumentor-signature__argument__default-value">null</span><span> ]</span></span><span class="phpdocumentor-signature__argument"><span>[</span><span>, </span><span class="phpdocumentor-signature__argument__return-type">string|null&nbsp;</span><span class="phpdocumentor-signature__argument__name">$csrfKey</span><span> = </span><span class="phpdocumentor-signature__argument__default-value">null</span><span> ]</span></span><span>)</span><span> : </span><span class="phpdocumentor-signature__response_type">mixed</span></code>
<section class="phpdocumentor-description"></section>
<h5 class="phpdocumentor-argument-list__heading">Parameters</h5>
<dl class="phpdocumentor-argument-list">
@ -358,6 +384,8 @@
: <span class="phpdocumentor-signature__argument__return-type">array&lt;string|int, mixed&gt;</span>
</dt>
<dd class="phpdocumentor-argument-list__definition">
<section class="phpdocumentor-description"><p>An array representing the user, which will be returned on a successful authentication. MUST include a 'me' key, may also contain a 'profile' key, or other keys at your discretion.</p>
</section>
</dd>
<dt class="phpdocumentor-argument-list__entry">
@ -365,13 +393,8 @@
: <span class="phpdocumentor-signature__argument__return-type">string</span>
</dt>
<dd class="phpdocumentor-argument-list__definition">
</dd>
<dt class="phpdocumentor-argument-list__entry">
<span class="phpdocumentor-signature__argument__name">$csrfKey</span>
: <span class="phpdocumentor-signature__argument__return-type">string|null</span>
= <span class="phpdocumentor-signature__argument__default-value">null</span> </dt>
<dd class="phpdocumentor-argument-list__definition">
<section class="phpdocumentor-description"><p>The password used to authenticate as $user, hashed by <code class="prettyprint">password_hash($pass, PASSWORD_DEFAULT)</code></p>
</section>
</dd>
<dt class="phpdocumentor-argument-list__entry">
@ -379,6 +402,17 @@
: <span class="phpdocumentor-signature__argument__return-type">string|null</span>
= <span class="phpdocumentor-signature__argument__default-value">null</span> </dt>
<dd class="phpdocumentor-argument-list__definition">
<section class="phpdocumentor-description"><p>The path to a template used to render the sign-in form. Uses default if null.</p>
</section>
</dd>
<dt class="phpdocumentor-argument-list__entry">
<span class="phpdocumentor-signature__argument__name">$csrfKey</span>
: <span class="phpdocumentor-signature__argument__return-type">string|null</span>
= <span class="phpdocumentor-signature__argument__default-value">null</span> </dt>
<dd class="phpdocumentor-argument-list__definition">
<section class="phpdocumentor-description"><p>The key under which to fetch a CSRF token from <code class="prettyprint">$request</code> attributes, and as the CSRF token name in submitted form data. Defaults to the Server default, only change if youre using a custom CSRF middleware.</p>
</section>
</dd>
</dl>
@ -405,7 +439,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/SingleUserPasswordAuthenticationCallback.php"><a href="files/src-callback-singleuserpasswordauthenticationcallback.html"><abbr title="src/Callback/SingleUserPasswordAuthenticationCallback.php">SingleUserPasswordAuthenticationCallback.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">34</span>
<span class="phpdocumentor-element-found-in__line">69</span>
</aside>

View File

@ -93,10 +93,19 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">13</span>
<span class="phpdocumentor-element-found-in__line">25</span>
</aside>
<p class="phpdocumentor-summary">Filesystem JSON Token Storage</p>
<section class="phpdocumentor-description"><p>An implementation of <code class="prettyprint">TokenStorageInterface</code> which stores authorization codes
and access tokens in the filesystem as JSON files, and supports custom access
token lifetimes.</p>
<p>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 havent written yet. I havent extensively documented this class, as it
will likely be superceded by the SQLite version.</p>
</section>
@ -290,7 +299,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">15</span>
<span class="phpdocumentor-element-found-in__line">27</span>
</aside>
@ -315,7 +324,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">14</span>
<span class="phpdocumentor-element-found-in__line">26</span>
</aside>
@ -340,7 +349,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">17</span>
<span class="phpdocumentor-element-found-in__line">29</span>
</aside>
@ -380,7 +389,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">21</span>
<span class="phpdocumentor-element-found-in__line">33</span>
</aside>
@ -410,7 +419,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">20</span>
<span class="phpdocumentor-element-found-in__line">32</span>
</aside>
@ -440,7 +449,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">24</span>
<span class="phpdocumentor-element-found-in__line">36</span>
</aside>
@ -470,7 +479,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">19</span>
<span class="phpdocumentor-element-found-in__line">31</span>
</aside>
@ -500,7 +509,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">22</span>
<span class="phpdocumentor-element-found-in__line">34</span>
</aside>
@ -534,7 +543,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">27</span>
<span class="phpdocumentor-element-found-in__line">39</span>
</aside>
@ -611,7 +620,7 @@
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">55</span>
<span class="phpdocumentor-element-found-in__line">67</span>
</aside>
<p class="phpdocumentor-summary">Create Auth Code</p>
@ -697,7 +706,7 @@ throw exceptions.</p>
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">196</span>
<span class="phpdocumentor-element-found-in__line">208</span>
</aside>
@ -739,7 +748,7 @@ throw exceptions.</p>
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">137</span>
<span class="phpdocumentor-element-found-in__line">149</span>
</aside>
@ -771,7 +780,7 @@ throw exceptions.</p>
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">69</span>
<span class="phpdocumentor-element-found-in__line">81</span>
</aside>
<p class="phpdocumentor-summary">Exchange Authorization Code for Access Token</p>
@ -829,7 +838,7 @@ expiry time, usually in a <code class="prettyprint">valid_until</code> key.</p>
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">165</span>
<span class="phpdocumentor-element-found-in__line">177</span>
</aside>
@ -871,7 +880,7 @@ expiry time, usually in a <code class="prettyprint">valid_until</code> key.</p>
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">115</span>
<span class="phpdocumentor-element-found-in__line">127</span>
</aside>
<p class="phpdocumentor-summary">Get Access Token</p>
@ -918,7 +927,7 @@ exactly the same way it was stored by <code class="prettyprint">exchangeAuthCode
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">206</span>
<span class="phpdocumentor-element-found-in__line">218</span>
</aside>
@ -960,7 +969,7 @@ exactly the same way it was stored by <code class="prettyprint">exchangeAuthCode
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">187</span>
<span class="phpdocumentor-element-found-in__line">199</span>
</aside>
@ -1009,7 +1018,7 @@ exactly the same way it was stored by <code class="prettyprint">exchangeAuthCode
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">131</span>
<span class="phpdocumentor-element-found-in__line">143</span>
</aside>
<p class="phpdocumentor-summary">Revoke Access Token</p>
@ -1055,7 +1064,7 @@ or false on error, including if the token did not exist.</p>
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">49</span>
<span class="phpdocumentor-element-found-in__line">61</span>
</aside>
@ -1097,7 +1106,7 @@ or false on error, including if the token did not exist.</p>
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">235</span>
<span class="phpdocumentor-element-found-in__line">247</span>
</aside>
@ -1139,7 +1148,7 @@ or false on error, including if the token did not exist.</p>
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Storage/FilesystemJsonStorage.php"><a href="files/src-storage-filesystemjsonstorage.html"><abbr title="src/Storage/FilesystemJsonStorage.php">FilesystemJsonStorage.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">211</span>
<span class="phpdocumentor-element-found-in__line">223</span>
</aside>

View File

@ -88,7 +88,7 @@
<dl class="phpdocumentor-table-of-contents">
<dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Taproot-IndieAuth-Callback-DefaultAuthorizationForm.html"><abbr title="\Taproot\IndieAuth\Callback\DefaultAuthorizationForm">DefaultAuthorizationForm</abbr></a></dt>
<dd></dd>
<dd>Default Authorization Form</dd>
</dl>

View File

@ -88,7 +88,7 @@
<dl class="phpdocumentor-table-of-contents">
<dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Taproot-IndieAuth-Storage-FilesystemJsonStorage.html"><abbr title="\Taproot\IndieAuth\Storage\FilesystemJsonStorage">FilesystemJsonStorage</abbr></a></dt>
<dd></dd>
<dd>Filesystem JSON Token Storage</dd>
</dl>

View File

@ -18,12 +18,12 @@ Search.appendIndex(
}, {
"fqsen": "\\Taproot\\IndieAuth\\Callback\\DefaultAuthorizationForm",
"name": "DefaultAuthorizationForm",
"summary": "",
"summary": "Default\u0020Authorization\u0020Form",
"url": "classes/Taproot-IndieAuth-Callback-DefaultAuthorizationForm.html"
}, {
"fqsen": "\\Taproot\\IndieAuth\\Callback\\DefaultAuthorizationForm\u003A\u003A__construct\u0028\u0029",
"name": "__construct",
"summary": "",
"summary": "Constructor",
"url": "classes/Taproot-IndieAuth-Callback-DefaultAuthorizationForm.html#method___construct"
}, {
"fqsen": "\\Taproot\\IndieAuth\\Callback\\DefaultAuthorizationForm\u003A\u003AshowForm\u0028\u0029",
@ -63,7 +63,7 @@ Search.appendIndex(
}, {
"fqsen": "\\Taproot\\IndieAuth\\Callback\\SingleUserPasswordAuthenticationCallback\u003A\u003A__construct\u0028\u0029",
"name": "__construct",
"summary": "",
"summary": "Constructor",
"url": "classes/Taproot-IndieAuth-Callback-SingleUserPasswordAuthenticationCallback.html#method___construct"
}, {
"fqsen": "\\Taproot\\IndieAuth\\Callback\\SingleUserPasswordAuthenticationCallback\u003A\u003A__invoke\u0028\u0029",
@ -528,7 +528,7 @@ Search.appendIndex(
}, {
"fqsen": "\\Taproot\\IndieAuth\\Storage\\FilesystemJsonStorage",
"name": "FilesystemJsonStorage",
"summary": "",
"summary": "Filesystem\u0020JSON\u0020Token\u0020Storage",
"url": "classes/Taproot-IndieAuth-Storage-FilesystemJsonStorage.html"
}, {
"fqsen": "\\Taproot\\IndieAuth\\Storage\\FilesystemJsonStorage\u003A\u003A__construct\u0028\u0029",

View File

@ -92,7 +92,7 @@
<dd>Authorization Form Interface</dd>
<dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Taproot-IndieAuth-Callback-DefaultAuthorizationForm.html"><abbr title="\Taproot\IndieAuth\Callback\DefaultAuthorizationForm">DefaultAuthorizationForm</abbr></a></dt>
<dd></dd>
<dd>Default Authorization Form</dd>
<dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Taproot-IndieAuth-Callback-SingleUserPasswordAuthenticationCallback.html"><abbr title="\Taproot\IndieAuth\Callback\SingleUserPasswordAuthenticationCallback">SingleUserPasswordAuthenticationCallback</abbr></a></dt>
<dd>Single User Password Authentication Callback</dd>

View File

@ -92,7 +92,7 @@
<dd>Token Storage Interface</dd>
<dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Taproot-IndieAuth-Storage-FilesystemJsonStorage.html"><abbr title="\Taproot\IndieAuth\Storage\FilesystemJsonStorage">FilesystemJsonStorage</abbr></a></dt>
<dd></dd>
<dd>Filesystem JSON Token Storage</dd>
<dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Taproot-IndieAuth-Storage-Sqlite3Storage.html"><abbr title="\Taproot\IndieAuth\Storage\Sqlite3Storage">Sqlite3Storage</abbr></a></dt>
<dd></dd>
<dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Taproot-IndieAuth-Storage-Token.html"><abbr title="\Taproot\IndieAuth\Storage\Token">Token</abbr></a></dt>

View File

@ -92,7 +92,7 @@
<dd>Token Storage Interface</dd>
<dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Taproot-IndieAuth-Callback-DefaultAuthorizationForm.html"><abbr title="\Taproot\IndieAuth\Callback\DefaultAuthorizationForm">DefaultAuthorizationForm</abbr></a></dt>
<dd></dd>
<dd>Default Authorization Form</dd>
<dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Taproot-IndieAuth-Callback-SingleUserPasswordAuthenticationCallback.html"><abbr title="\Taproot\IndieAuth\Callback\SingleUserPasswordAuthenticationCallback">SingleUserPasswordAuthenticationCallback</abbr></a></dt>
<dd>Single User Password Authentication Callback</dd>
<dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Taproot-IndieAuth-IndieAuthException.html"><abbr title="\Taproot\IndieAuth\IndieAuthException">IndieAuthException</abbr></a></dt>
@ -108,7 +108,7 @@
<dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Taproot-IndieAuth-Server.html"><abbr title="\Taproot\IndieAuth\Server">Server</abbr></a></dt>
<dd>IndieAuth Server</dd>
<dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Taproot-IndieAuth-Storage-FilesystemJsonStorage.html"><abbr title="\Taproot\IndieAuth\Storage\FilesystemJsonStorage">FilesystemJsonStorage</abbr></a></dt>
<dd></dd>
<dd>Filesystem JSON Token Storage</dd>
<dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Taproot-IndieAuth-Storage-Sqlite3Storage.html"><abbr title="\Taproot\IndieAuth\Storage\Sqlite3Storage">Sqlite3Storage</abbr></a></dt>
<dd></dd>
<dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Taproot-IndieAuth-Storage-Token.html"><abbr title="\Taproot\IndieAuth\Storage\Token">Token</abbr></a></dt>

View File

@ -12,6 +12,26 @@ use Psr\Log\NullLogger;
use function Taproot\IndieAuth\renderTemplate;
/**
* Default Authorization Form
*
* This implementation of `AuthorizationFormInterface` is used by `Server` if the user doesnt
* provide one of their own. It presents the user with a simple consent screen, showing any
* available details about the client app, and allowing the user to grant any requested scopes.
*
* When the form is submitted, any granted scopes are then added to the authorization code data.
*
* You can customise the authorization template used by passing a path to your own template to
* the constructor. Refer to the default template `/templates/default_authorization_page.html.php`
* as a starting point.
*
* If you want to add additional form controls (e.g. configurable token lifetimes), as well as
* making a new template, youll need to make a subclass which overrides `transformAuthorizationCode()`
* to additionally handle your new form data.
*
* For any more involved customisation (for example using a templating library of your choice), it
* may make sense to create your own implementation of `AuthorizationFormInterface`.
*/
class DefaultAuthorizationForm implements AuthorizationFormInterface, LoggerAwareInterface {
public string $csrfKey;
@ -19,6 +39,13 @@ class DefaultAuthorizationForm implements AuthorizationFormInterface, LoggerAwar
public LoggerInterface $logger;
/**
* Constructor
*
* @param string|null $formTemplatePath The path to a custom template. Uses the default if null.
* @param string|null $csrfKey The key used to retrieve a CSRF token from the request attributes, and as its form data name. Uses the default defined in Server if null. Only change this if youre using a custom CSRF middleware.
* @param LoggerInterface|null $logger A logger.
*/
public function __construct(?string $formTemplatePath=null, ?string $csrfKey=null, ?LoggerInterface $logger=null) {
$this->formTemplatePath = $formTemplatePath ?? __DIR__ . '/../../templates/default_authorization_page.html.php';
$this->csrfKey = $csrfKey ?? \Taproot\IndieAuth\Server::DEFAULT_CSRF_KEY;

View File

@ -11,7 +11,34 @@ use function Taproot\IndieAuth\renderTemplate;
/**
* Single User Password Authentication Callback
*
* A simple example authentication callback which performs authentication itself rather
* than redirecting to an existing authentication flow.
*
* In some cases, it may make sense for your IndieAuth server to be able to authenticate
* users itself, rather than redirecting them to an existing authentication flow. This
* implementation provides a simple single-user password authentication method intended
* for bootstrapping and testing purposes.
*
* The sign-in form can be customised by making your own template and passing the path to
* the constructor.
*
* Minimal usage:
*
* // One-off during app configuration:
* YOUR_HASHED_PASSWORD = password_hash('my super strong password', PASSWORD_DEFAULT);
*
* // In your app:
* use Taproot\IndieAuth;
* $server = new IndieAuth\Server([
*
* 'handleAuthenticationRequestCallback' => new IndieAuth\Callback\SingleUserPasswordAuthenticationCallback(
* ['me' => 'https://me.example.com/'],
* YOUR_HASHED_PASSWORD
* )
*
* ]);
*
* See documentation for `__construct()` for information about customising behaviour.
*/
class SingleUserPasswordAuthenticationCallback {
const PASSWORD_FORM_PARAMETER = 'taproot_indieauth_server_password';
@ -21,7 +48,15 @@ class SingleUserPasswordAuthenticationCallback {
protected array $user;
protected string $hashedPassword;
public function __construct(array $user, string $hashedPassword, ?string $csrfKey=null, ?string $formTemplate=null) {
/**
* Constructor
*
* @param array $user An array representing the user, which will be returned on a successful authentication. MUST include a 'me' key, may also contain a 'profile' key, or other keys at your discretion.
* @param string $hashedPassword The password used to authenticate as $user, hashed by `password_hash($pass, PASSWORD_DEFAULT)`
* @param string|null $formTemplate The path to a template used to render the sign-in form. Uses default if null.
* @param string|null $csrfKey The key under which to fetch a CSRF token from `$request` attributes, and as the CSRF token name in submitted form data. Defaults to the Server default, only change if youre using a custom CSRF middleware.
*/
public function __construct(array $user, string $hashedPassword, ?string $formTemplate=null, ?string $csrfKey=null) {
if (!array_key_exists('me', $user) || !is_string($user['me'])) {
throw new Exception('The $user array MUST contain a “me” key, the value which must be the users canonical URL as a string.');
}

View File

@ -10,6 +10,18 @@ use Psr\Log\NullLogger;
use function Taproot\IndieAuth\generateRandomString;
/**
* 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 havent written yet. I havent extensively documented this class, as it
* will likely be superceded by the SQLite version.
*/
class FilesystemJsonStorage implements TokenStorageInterface, LoggerAwareInterface {
const DEFAULT_AUTH_CODE_TTL = 60 * 5; // Five minutes.
const DEFAULT_ACCESS_TOKEN_TTL = 60 * 60 * 24 * 7; // One week.