bit-badger/feed-reader-central
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 12 Activity

Add docs for security models (#9)

Browse Source 
- Change default security to CONFIGURE_ME
- Fix log on return URL handling
- Update INSTALLING security model descriptions
This commit is contained in:
Daniel J. Summers
2024-04-27 18:54:57 -04:00
parent 9611893da3
commit 36373aae01
8 changed files with 119 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
src/public/assets/style.css
View File

@@ -70,6 +70,10 @@ article {
}
}
}
article.docs {
line-height: 1.4rem;
}
input[type=url],
input[type=text],
input[type=email],
@@ -103,3 +107,9 @@ button:hover,
flex-flow: row nowrap;
justify-content: space-evenly;
}
code {
font-size: .9rem;
}
p.back-link {
margin-top: -1rem;
}

15
src/public/docs/index.php Normal file
View File

@@ -0,0 +1,15 @@
<?php
include '../../start.php';
$db = Data::getConnection();
Security::verifyUser($db, redirectIfAnonymous: false);
page_head('Documentation'); ?>
<h1>Documentation Home</h1>
<article>
<p><a href=./the-cli>About the CLI</a> provides orientation on Feed Reader Central&rsquo;s command line interface
<p><a href=./security-modes>Configuring Security Modes</a> describes the three security modes and how to manage each
of them
</article><?php
page_foot();
$db->close();

62
src/public/docs/security-modes.php Normal file
View File

@@ -0,0 +1,62 @@
<?php
include '../../start.php';
$db = Data::getConnection();
Security::verifyUser($db, redirectIfAnonymous: false);
page_head('Security Modes | Documentation'); ?>
<h1>Configuring Security Modes</h1>
<p class=back-link><a href=./>&lang;&lang; Documentation Home</a>
<article class=docs>
<h2>Security Modes</h2>
<p><strong>Single-User</strong> mode assumes that every connection to the application is the same person. It is
designed for one person to use on a trusted internal network; under no circumstances should an instance
configured this way be reachable from the Internet. However, it is a low-friction way to keep up with feeds from
multiple devices on a home network.
<p><strong>Single-User with Password</strong> mode operates the same way as Single-User mode does, but the
application will require a password. Depending on the strength of the password, this model may be appropriate
for Internet access, but its intent is more for keeping other internal network users from accessing the site
and reading the items before its intended user is able to do so. The password should be set using the CLI.
<p><strong>Multi-User</strong> mode requires both an e-mail address and password before allowing the user to
proceed. It is the most appropriate configuration for an Internet-facing instance, and it can also be used to
provide access to multiple users on an internal network. Managing users is performed via the CLI.
<h2 id=manage-users>Managing Users in Multi-User Mode</h2>
<p>Users can be added or deleted, and passwords set, using the <code>user</code> CLI utility.<br><br>
<em>(For all the &ldquo;password&rdquo; parameters, if a character in the password conflicts with a shell escape
character, enclose the password in double-quotes for *sh or single-quotes for PowerShell.)</em>
<h3>Add a User</h3>
<p><code>php-cli utils/user.php add-user alice@example.com AlicesSecur3P4ssword</code>
<p>The utility should respond with the e-mail address and password that were added. If a user with that e-mail
address already exists, the utility will not add it again.
<h3>Set a User&rsquo;s Password</h3>
<p><code>php-cli utils/user.php set-password bob@example.com AN3wPassCauseB0bForg0t1t</code>
<h3>Delete a User</h3>
<p><code>php-cli utils/user.php delete-user carol@example.com</code>
<p>The utility will require confirmation that the user and their feeds should be deleted. Any input that starts with
the letter &ldquo;y&rdquo; will confirm, and any other input will cancel the process.
<h2 id=change-to-multi>Changing from Single-User to Multi-User Mode</h2>
<p>In Single-User mode, the application uses a known e-mail address and password to mimic multi-user mode where that
user is always logged on. If you have been using the application this way, and decide that you want to run in
multi-user mode instead, you will need to update <code>SECURITY_MODEL</code> in <code>user-config.php</code> to
<code>Security::MULTI_USER</code>.
<p>The e-mail address used for Single-User mode is not allowed to log on in Multi-User mode. If you want to preserve
the feeds defined by the single user, use the CLI to replace its e-mail address and password.
<p><code>php-cli utils/user.php migrate-single-user dave@example.com Dav3sPas$wort</code>
<p>If, however, you do not wish to maintain the single user&rsquo;s information at all, delete it.
<p><code>php-cli utils/user.php remove-single-user</code>
<h2 id=change-multi-to-single>Changing from Multi-User to any Single-User Mode</h2>
<p>This scenario is possible, but not really advisable. When the application is in any Single-User mode, it only
displays feeds from the Single-User mode user. The information for the other users remains in the database,
though, so this change is not destructive.
<h2 id=change-single-to-pw>Changing from Single-User to Single-User with Password Mode</h2>
<p>Set <code>SECURITY_MODEL</code> in <code>user-config.php</code> to
<code>Security::SINGLE_USER_WITH_PASSWORD</code>, then use the <code>user</code> CLI utility to set a password.
<p><code>php-cli util/user.php set-single-password aNiceC0mplexPassw0rd</code>
<h2 id=change-pw-to-single>Changing from Single-User with Password to Single-User Mode</h2>
<p>If you decide you do not want to enter a password, but want to maintain single-user mode, set
<code>SECURITY_MODEL</code> in <code>user-config.php</code> to <code>Security::SINGLE_USER</code>, then run the
<code>user</code> CLI utility to reset the single user back to its expected default.
<p><code>php-cli util/user.php reset-single-password</code>
</article><?php
page_foot();
$db->close();

24
src/public/docs/the-cli.php Normal file
View File

@@ -0,0 +1,24 @@
<?php
include '../../start.php';
$db = Data::getConnection();
Security::verifyUser($db, redirectIfAnonymous: false);
page_head('About the CLI | Documentation'); ?>
<h1>About the CLI</h1>
<p class=back-link><a href=./>&lang;&lang; Documentation Home</a>
<article class=docs>
<p>Feed Reader Central&rsquo;s low-friction design includes having many administrative tasks run in a terminal or
shell. &ldquo;CLI&rdquo; is short for &ldquo;Command Line Interface&rdquo;, and refers to commands that are run
via PHP&rsquo;s <code>php-cli</code> command. Ensure that the version of PHP installed also has that feature
enabled. (If you are using the recommended
<a href=https://frankenphp.dev target=_blank rel=noopener>FrankenPHP</a> environment, it has PHP CLI support;
use <code>frankenphp php-cli</code> instead of <code>php-cli</code> when following instructions here.)
<h2>Running CLI Commands</h2>
<p>CLI commands should be run from the same directory with <code>start.php</code>; this will be one directory level
up from <code>/public</code>, the web root directory. CLI utilities are in the <code>/util</code> directory, so
an invocation will follow the pattern:
<p><code>php-cli util/some-process.php command option1 option2</code>
</article><?php
page_foot();
$db->close();

2
src/public/user/log-on.php
View File

@@ -8,7 +8,7 @@ Security::verifyUser($db, redirectIfAnonymous: false);
if (array_key_exists(Key::USER_ID, $_SESSION)) frc_redirect('/');
if ($_SERVER['REQUEST_METHOD'] == 'POST') {
Security::logOnUser($_POST['email'] ?? '', $_POST['password'], $_POST['returnTo'], $db);
Security::logOnUser($_POST['email'] ?? '', $_POST['password'], $_POST['returnTo'] ?? null, $db);
// If we're still here, something didn't work; preserve the returnTo parameter
$_GET['returnTo'] = $_POST['returnTo'];
}