diff --git a/INSTALLING.md b/INSTALLING.md index 9497134..70854f8 100644 --- a/INSTALLING.md +++ b/INSTALLING.md @@ -17,7 +17,7 @@ _(More environments will be detailed as part of a later release; an nginx revers ## PHP Requirements -This is written to target PHP 8.3, and requires the `curl`, `DOM`, and `SQLite3` modules. _(FrankenPHP contains these modules as part of its build.)_ +This is written to target PHP 8.3, and requires the `curl`, `DOM`, and `SQLite3` modules and the `php-cli` feature. _(FrankenPHP contains all these as part of its build.)_ # Setup and Configuration @@ -31,10 +31,10 @@ Within the `/src` directory, there is a file named `user-config.php`. This file ### Security Model -There ~~are~~ will be three supported security models, designed around different ways the software may be deployed. +There are three supported security models, designed around different ways the software may be deployed. `SECURITY_MODEL` in `user-config.php` **must be set** to one of these values. - `Securty::SINGLE_USER` assumes that all connections to the instance are the same person. There is no password required, and no username or e-mail address will be displayed for that user. This is a good setup for a single user on a home intranet. **DO NOT PUT AN INSTANCE WITH THIS CONFIGURATION ON THE PUBLIC INTERNET!** If you do, you deserve what you get. -- `Security::SINGLE_USER_WITH_PASSWORD` _(not yet implemented)_ will be the same as the above, but will require a password. This setup is ideal for intranets where the user does not want any other users ending up marking their feeds as read just by browsing them. -- `Security::MULTI_USER` _(not yet implemented)_ will require a known e-mail address and password be provided to establish the identity of each user. This will be the most appropriate setup for an Internet-facing instance, even if there is only one user. +- `Security::SINGLE_USER_WITH_PASSWORD` is the same as the above but requires a password. This setup is ideal for intranets where the user does not want any other users ending up marking their feeds as read just by browsing them. +- `Security::MULTI_USER` requires a known e-mail address and password be provided to establish the identity of each user. This is the most appropriate setup for an Internet-facing instance, even if there is only one user. ### Database Name diff --git a/src/public/assets/style.css b/src/public/assets/style.css index f3d7654..9ce2647 100644 --- a/src/public/assets/style.css +++ b/src/public/assets/style.css @@ -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; +} diff --git a/src/public/docs/index.php b/src/public/docs/index.php new file mode 100644 index 0000000..13ad8c9 --- /dev/null +++ b/src/public/docs/index.php @@ -0,0 +1,15 @@ + +

Documentation Home

+
+

About the CLI provides orientation on Feed Reader Central’s command line interface +

Configuring Security Modes describes the three security modes and how to manage each + of them +

close(); diff --git a/src/public/docs/security-modes.php b/src/public/docs/security-modes.php new file mode 100644 index 0000000..32ddf49 --- /dev/null +++ b/src/public/docs/security-modes.php @@ -0,0 +1,62 @@ + +

Configuring Security Modes

+

⟨⟨ Documentation Home +

+

Security Modes

+

Single-User 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. +

Single-User with Password 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. +

Multi-User 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. +

Managing Users in Multi-User Mode

+

Users can be added or deleted, and passwords set, using the user CLI utility.

+ (For all the “password” 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.) +

Add a User

+

php-cli utils/user.php add-user alice@example.com AlicesSecur3P4ssword +

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. +

Set a User’s Password

+

php-cli utils/user.php set-password bob@example.com AN3wPassCauseB0bForg0t1t +

Delete a User

+

php-cli utils/user.php delete-user carol@example.com +

The utility will require confirmation that the user and their feeds should be deleted. Any input that starts with + the letter “y” will confirm, and any other input will cancel the process. +

Changing from Single-User to Multi-User Mode

+

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 SECURITY_MODEL in user-config.php to + Security::MULTI_USER. +

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. +

php-cli utils/user.php migrate-single-user dave@example.com Dav3sPas$wort +

If, however, you do not wish to maintain the single user’s information at all, delete it. +

php-cli utils/user.php remove-single-user +

Changing from Multi-User to any Single-User Mode

+

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. +

Changing from Single-User to Single-User with Password Mode

+

Set SECURITY_MODEL in user-config.php to + Security::SINGLE_USER_WITH_PASSWORD, then use the user CLI utility to set a password. +

php-cli util/user.php set-single-password aNiceC0mplexPassw0rd +

Changing from Single-User with Password to Single-User Mode

+

If you decide you do not want to enter a password, but want to maintain single-user mode, set + SECURITY_MODEL in user-config.php to Security::SINGLE_USER, then run the + user CLI utility to reset the single user back to its expected default. +

php-cli util/user.php reset-single-password +

close(); diff --git a/src/public/docs/the-cli.php b/src/public/docs/the-cli.php new file mode 100644 index 0000000..80aec65 --- /dev/null +++ b/src/public/docs/the-cli.php @@ -0,0 +1,24 @@ + +

About the CLI

+

⟨⟨ Documentation Home +

+

Feed Reader Central’s low-friction design includes having many administrative tasks run in a terminal or + shell. “CLI” is short for “Command Line Interface”, and refers to commands that are run + via PHP’s php-cli command. Ensure that the version of PHP installed also has that feature + enabled. (If you are using the recommended + FrankenPHP environment, it has PHP CLI support; + use frankenphp php-cli instead of php-cli when following instructions here.) +

Running CLI Commands

+

CLI commands should be run from the same directory with start.php; this will be one directory level + up from /public, the web root directory. CLI utilities are in the /util directory, so + an invocation will follow the pattern: +

php-cli util/some-process.php command option1 option2 +

close(); diff --git a/src/public/user/log-on.php b/src/public/user/log-on.php index 64f4aab..63dc93e 100644 --- a/src/public/user/log-on.php +++ b/src/public/user/log-on.php @@ -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']; } diff --git a/src/start.php b/src/start.php index 9261221..406cf50 100644 --- a/src/start.php +++ b/src/start.php @@ -60,10 +60,10 @@ function page_head(string $title): void {
Feed Reader Centralv
Add Feed | Log Off'; + echo 'Add Feed | Docs | Log Off'; if ($_SESSION[Key::USER_EMAIL] != Security::SINGLE_USER_EMAIL) echo " | {$_SESSION[Key::USER_EMAIL]}"; } else { - echo 'Log On'; + echo 'Log On | Docs'; } ?>
diff --git a/src/user-config.php b/src/user-config.php index a89cefe..e0ca5f8 100644 --- a/src/user-config.php +++ b/src/user-config.php @@ -12,7 +12,7 @@ * - Security::SINGLE_USER_WITH_PASSWORD (no e-mail required, does require a password) * - Security::MULTI_USER (e-mail and password required for all users) */ -const SECURITY_MODEL = Security::SINGLE_USER; +const SECURITY_MODEL = 'CONFIGURE_ME'; /** The name of the database file where users and feeds should be kept */ const DATABASE_NAME = 'frc.db';