rewrite the user authentication example to use the latest features

Author: lovasoa

examples/user-authentication/README.md

@@ -1,23 +1,39 @@
 # User authentication demo
 
-This example demonstrates how to manually handle user authentication with SQLpage and PostgreSQL.
-All the user and password management is done in the database, using the standard [pgcrypto](https://www.postgresql.org/docs/current/pgcrypto.html) postgresql extension.
+This example demonstrates how to handle user authentication with SQLpage.
+
+It uses a PostgreSQL database to store user information and session ids,
+but the same principles can be applied to other databases.
+
+All the user and password management is done in SQLPage,
+which uses [best practices](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#maximum-password-lengths) for password storage.
 
 This demonstrates how to implement:
- - [a signup form](./sign%20up.sql)
- - [a login form](./sign%20in.sql)
+ - [a signup form](./signup.sql)
+ - [a login form](./signin.sql)
  - [a logout button](./logout.sql)
  - [secured pages](./protected_page.sql) that can only be accessed by logged-in users
 
 User authentication is a complex topic, and you can follow the work on implementing differenet authentication methods in [this issue](https://github.com/lovasoa/SQLpage/issues/12).
 
+## How to run
+
+Install [docker](https://docs.docker.com/get-docker/) and [docker-compose](https://docs.docker.com/compose/install/).
+
+Then run the following command in this directory:
+
+```bash
+docker-compose up
+```
+
+Then open [http://localhost:8080](http://localhost:8080) in your browser.
+
 ## Caveats
 
-In this example, we store encrypted user passwords in the database, but we let the database itself handle the encryption.
-For that to be safe, you need to make sure that:
- - the database is not accessible by untrusted users
- - the database logs and configuration files are not accessible by untrusted users
- - either your connection to the database is encrypted [(use SSL)](https://www.postgresql.org/docs/current/ssl-tcp.html) or you can trust all the machines on the network between your application and the database. Connections should be encrypted by default if you use a recent version of PostgreSQL and a popular distribution.
+In this example, we handle user creation and login in SQLpage.
+
+If you are implementing user authentication in an public application with potentially sensitive data,
+you should propably read the [Authentication Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html) from OWASP.
 
 ## Screenshots
 
@@ -30,28 +46,40 @@ For that to be safe, you need to make sure that:
 
 ### User creation
 
-The [signup form](./sign%20up.sql) is a simple form that is handled by [`create_user.sql`](./create_user.sql).
+The [signup form](./signup.sql) is a simple form that is handled by [`create_user.sql`](./create_user.sql).
 You could restrict user creation to existing administrators and create an initial administrator in a database migration.
 
 ### User login
 
-The [login form](./sign%20in.sql) is a simple form that is handled by [`login.sql`](./login.sql).
-It checks that the username exists and that the password is correct using the [pgcrypto](https://www.postgresql.org/docs/current/pgcrypto.html) extension with
+The [login form](./signin.sql) is a simple form that is handled by [`login.sql`](./login.sql).
+
+`login.sql` checks that the username exists and that the password is correct using the [authentication component](https://sql.ophir.dev/documentation.sql?component=authentication#component) extension with
 
 ```sql
-SELECT * FROM users WHERE username = :username AND password = crypt(:password, password);
+SELECT 'authentication' AS component,
+    'signin.sql' AS link,
+    (SELECT password_hash FROM user_info WHERE username = :username) AS password_hash,
+    :password AS password;
 ```
 
 If the login is successful, an entry is added to the [`login_session`](./sqlpage/migrations/0000_init.sql) table with a random session id.
+
+If it is not, the authentication component will redirect the user to the login page and stop the execution of the page.
+
 The session id is then stored in a cookie on the user's browser.
 
-The user is then redirected to [`./check_login.sql`](./check_login.sql) that checks that the session id is valid and redirects back to the login page if it is not.
+The user is then redirected to [`./protected_page.sql`](./protected_page.sql) which will check that the user is logged in.
 
 ### Protected pages
 
 Protected pages are pages that can only be accessed by logged-in users.
-There is an example in [`protected_page.sql`](./protected_page.sql) that uses a simple [postgresql stored procedure](./sqlpage/migrations/0000_init.sql)
- to raise an error (and thus prevent content rendering) if the user is not logged in.
+
+There is an example in [`protected_page.sql`](./protected_page.sql) that uses
+the [`redirect`](https://sql.ophir.dev/documentation.sql?component=redirect#component)
+component to redirect the user to the login page if they are not logged in.
+
+Checking whether the user is logged in is as simple as checking that session id returned by [`sqlpage.cookie('session')`](https://sql.ophir.dev/functions.sql?function=cookie#function) exists in the [`login_session`](./sqlpage/migrations/0000_init.sql) table.
+
 
 ### User logout
 

examples/user-authentication/create_user.sql

@@ -1,21 +1,21 @@
 WITH inserted_user AS (
     INSERT INTO user_info (username, password_hash)
-    VALUES (:username, crypt(:password, gen_salt('bf', 10)))
+    VALUES (:username, sqlpage.hash_password(:password))
     ON CONFLICT (username) DO NOTHING
     RETURNING username
 )
 SELECT 'hero' AS component,
     'Welcome' AS title,
     'Welcome, ' || username || '! Your user account was successfully created. You can now log in.' AS description,
     'https://upload.wikimedia.org/wikipedia/commons/thumb/e/e1/Community_wp20.png/974px-Community_wp20.png' AS image,
-    'sign in.sql' AS link,
+    'signin.sql' AS link,
     'Log in' AS link_text
 FROM inserted_user
 UNION ALL
 SELECT 'hero' AS component,
     'Sorry' AS title,
     'Sorry, this user name is already taken.' AS description_md,
     'https://upload.wikimedia.org/wikipedia/commons/thumb/f/f0/Sad_face_of_a_Wayuu_Woman.jpg/640px-Sad_face_of_a_Wayuu_Woman.jpg' AS image,
-    'sign up.sql' AS link,
+    'signup.sql' AS link,
     'Try again' AS link_text
 WHERE NOT EXISTS (SELECT 1 FROM inserted_user);

examples/user-authentication/generate_password_hash.sql

@@ -0,0 +1,5 @@
+SELECT 'form' AS component;
+SELECT 'password' AS name, 'Password to create a hash for' AS label, :password AS value;
+
+SELECT 'code' AS component;
+SELECT sqlpage.hash_password(:password) AS contents;

examples/user-authentication/index.sql

@@ -2,12 +2,12 @@ SELECT 'shell' AS component,
     'User Management App' AS title,
     'user' AS icon,
     '/' AS link,
-    'sign in' AS menu_item,
-    'sign up' AS menu_item;
+    'signin' AS menu_item,
+    'signup' AS menu_item;
 
 SELECT 'hero' AS component,
     'SQLPage Authentication Demo' AS title,
     'This application requires signing up to view the protected page.' AS description_md,
     'https://upload.wikimedia.org/wikipedia/commons/thumb/e/e1/Community_wp20.png/974px-Community_wp20.png' AS image,
-    'login_check.sql' AS link,
+    'protected_page.sql' AS link,
     'Access protected page' AS link_text;

examples/user-authentication/login.sql

@@ -1,10 +1,15 @@
-INSERT INTO login_session (username)
-SELECT username
-FROM user_info
-WHERE username = :username
-    AND password_hash = crypt(:password, password_hash)
-RETURNING 'cookie' AS component,
-    'session' AS name,
-    id AS value;
-SELECT 'http_header' AS component,
-    'login_check.sql' AS location;
+-- The authentication component will stop the execution of the page and redirect the user to the login page if
+-- the password is incorrect or if the user does not exist.
+SELECT 'authentication' AS component,
+    'signin.sql?error' AS link,
+    (SELECT password_hash FROM user_info WHERE username = :username) AS password_hash,
+    :password AS password;
+
+-- Generate a random 32 characters session ID, insert it into the database,
+-- and save it in a cookie on the user's browser.
+INSERT INTO login_session (id, username)
+VALUES (sqlpage.random_string(32), :username)
+RETURNING 'cookie' AS component, 'session' AS name, id AS value;
+
+-- Redirect the user to the protected page.
+SELECT 'redirect' AS component, 'protected_page.sql' AS link;

examples/user-authentication/login_check.sql

@@ -1,4 +1,4 @@
 DELETE FROM login_session WHERE id = sqlpage.cookie('session');
 SELECT 'cookie' AS component, 'session' AS name, TRUE AS remove;
 
-SELECT 'http_header' AS component, 'login.sql' AS location;
+SELECT 'redirect' AS component, '/' AS location;

examples/user-authentication/logout.sql

@@ -1,6 +1,10 @@
-SELECT raise_error('Invalid credentials, please log in') WHERE NOT is_valid_session(sqlpage.cookie('session'));
+SELECT 'redirect' AS component,
+        'signin.sql?error' AS link
+WHERE logged_in_user(sqlpage.cookie('session')) IS NULL;
 
 SELECT 'shell' AS component, 'Protected page' AS title, 'lock' AS icon, '/' AS link, 'logout' AS menu_item;
 
 SELECT 'text' AS component,
-        'This content is [top secret](https://youtu.be/dQw4w9WgXcQ). You cannot view it if you are not connected.' AS contents_md;
+        'Welcome, ' || logged_in_user(sqlpage.cookie('session')) || ' !' AS title,
+        'This content is [top secret](https://youtu.be/dQw4w9WgXcQ).
+        You cannot view it if you are not connected.' AS contents_md;

examples/user-authentication/protected_page.sql

@@ -0,0 +1,14 @@
+SELECT 'form' AS component,
+    'Sign in' AS title,
+    'Sign in' AS validate,
+    'login.sql' AS action;
+
+SELECT 'username' AS name;
+SELECT 'password' AS name, 'password' AS type;
+
+SELECT 'alert' as component,
+    'Sorry' as title,
+    'We could not authenticate you. Please log in or [create an account](signup.sql).' as description_md,
+    'alert-circle' as icon,
+    'red' as color
+WHERE $error IS NOT NULL;

examples/user-authentication/sign in.sql

@@ -4,5 +4,5 @@ SELECT 'form' AS component,
     'create_user.sql' AS action;
 
 SELECT 'username' AS name;
-SELECT 'password' AS name, 'password' AS type;
+SELECT 'password' AS name, 'password' AS type, '^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]{8,}$' AS pattern, 'Password must be at least 8 characters long and contain at least one letter and one number.' AS description;
 SELECT 'terms' AS name, 'I accept the terms and conditions' AS label, TRUE AS required, FALSE AS value, 'checkbox' AS type;

examples/user-authentication/signin.sql

@@ -4,7 +4,14 @@ CREATE TABLE user_info (
 );
 
 CREATE TABLE login_session (
-    id TEXT PRIMARY KEY DEFAULT encode(gen_random_bytes(128), 'hex'),
+    id TEXT PRIMARY KEY,
     username TEXT NOT NULL REFERENCES user_info(username),
     created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
-);
+);
+
+-- A small pure utility function to get the current user from a session cookie.
+-- In a database that does not support functions, you could inline this query
+-- or use a view if you need more information from the user table
+CREATE FUNCTION logged_in_user(session_id TEXT) RETURNS TEXT AS $$
+    SELECT username FROM login_session WHERE id = session_id;
+$$ LANGUAGE SQL STABLE;

examples/user-authentication/sign up.sql renamed to examples/user-authentication/signup.sql

@@ -0,0 +1,4 @@
+-- Creates an initial user called 'admin'
+-- with a password hash that was generated using the 'generate_password_hash.sql' page.
+INSERT INTO user_info (username, password_hash)
+VALUES ('admin', '$argon2id$v=19$m=19456,t=2,p=1$IiReWDP0ocWvia+fTdozJw$53EozOKX7HkpvOdoWHjsh9yKvRN2TmQm/PjYBeaOqqc');