feat: add base auth docs

Author: mychidarko

.vitepress/config/sidebar.ts

@@ -95,17 +95,17 @@ const sidebar = [
     // collapsed: true,
     items: [
       { text: 'Introduction', link: '/docs/auth/' },
-      { text: 'MVC Support', link: '/docs/auth/mvc' },
-      { text: 'Auth Config', link: '/docs/auth/config' },
+      // { text: 'MVC Support', link: '/docs/auth/mvc' },
+      // { text: 'Auth Config', link: '/docs/auth/config' },
       { text: 'User Login', link: '/docs/auth/login' },
       { text: 'User Sign Up', link: '/docs/auth/signup' },
-      { text: 'Auth Session', link: '/docs/auth/session' },
+      // { text: 'Auth Session', link: '/docs/auth/session' },
       {
-        text: 'Protected Routes',
+        text: 'Protecting your routes',
         link: '/docs/auth/protected-routes',
       },
       { text: 'Updating logged-in user', link: '/docs/auth/update' },
-      { text: 'Helper methods', link: '/docs/auth/helpers' },
+      { text: 'Build your own auth library', link: '/docs/auth/helpers' },
     ],
   },
   {

src/docs/auth/config.md

@@ -1 +1,73 @@
 # Auth Config
+
+We understand that every application is different and may require a different level of control over the authentication system. Whether you want to use tokens, sessions, or your own custom setup, you can configure it without any hassle.
+
+Leaf Auth is flexible enough to adapt to whatever system works best for you.
+
+If you are using Leaf MVC, we have already created a config file available at `config/auth.php`. You can follow this documentation to update your config file.
+
+## Specifying the table to use
+
+Leaf assumes that you will save your users in a table named `users`. If you want to use a different table, you can configure Leaf Auth using `db.table`:
+
+```php:no-line-numbers
+auth()->config('db.table', 'admins');
+```
+
+## Specifying the primary key
+
+Most databases use `id` as the primary key. If you are using a different field as the primary key, you can configure Leaf Auth using `id.key`:
+
+```php:no-line-numbers
+auth()->config('id.key', 'admin_id');
+```
+
+If you are using UUIDs as your primary key, you can configure Leaf Auth to use them:
+
+```php:no-line-numbers
+auth()->config('id.uuid', UUID::v4());
+```
+
+## Using timestamps
+
+Leaf will always try to set the `created_at` and `updated_at` fields in your database. If you want to turn this off, you can set `timestamps` to `false`:
+
+```php:no-line-numbers
+auth()->config('timestamps', false);
+```
+
+Different databases have different ways of handling timestamps. If you get an error concerning the format of the timestamp, you can configure Leaf Auth to use a different format:
+
+```php:no-line-numbers
+auth()->config('timestamps.format', 'YYYY-MM-DD HH:MM:SS');
+```
+
+You can find the date format documentation [here](/docs/utils/date#formatting-dates).
+
+## Create session on registration
+
+Leaf will require a user to manually login after registration. If you want to automatically log in a user after registration, you can configure Leaf Auth to do that:
+
+```php:no-line-numbers
+auth()->config('session.register', true);
+```
+
+You can also set the redirect URL after registration:
+
+```php:no-line-numbers
+auth()->config('session.registerRedirect', '/dashboard');
+```
+
+## Auth with tokens
+
+This is the default way Leaf handles authentication. There are a few things you can configure to make your token authentication more secure like the token lifetime:
+
+```php:no-line-numbers
+auth()->config('token.lifetime', 3600); // 1 hour
+```
+
+You can also set the secret key for your tokens:
+
+```php:no-line-numbers
+auth()->config('token.secret', 'your-secret-key');
+```

src/docs/auth/helpers.md

@@ -1 +1,137 @@
-# Helper Methods
+# Build your own auth library
+
+Leaf Auth already provides everything you need to get a full authentication system up and running. However, if you want to build your own custom authentication system from the ground up, Leaf provides you with the tools to do that.
+
+## Working with JWTs
+
+According to the JWT docs, JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.
+
+In authentication, you can use JWTs as an identifier that a user has successfully logged in. The JWT usually also contains information about the authenticated user, usually the user's id. Leaf auth has helpers for interacting with JWTs. We'll take a look at them in this document.
+
+## Generating JWTs
+
+Leaf provides multiple ways for generating JWTs.
+
+- ### Using the `generateSimpleToken` method
+
+  The simplest method is to use the `generateSimpleToken` method on the `Leaf\Helpers\Authentication` class. This method takes in 3 parameters:
+
+  - The user id of the currently authenticated user
+  - The jwt secret string
+  - The jwt expiry time in seconds
+
+  ```php
+  use Leaf\Helpers\Authentication;
+
+  // ... your application code
+
+  Authentication::generateSimpleToken(
+      $userId,
+      'MY_JWT_SECRET_STRING',
+      time() + 3600
+  );
+  ```
+
+- ### Using the `generateToken` method
+
+  The `generateToken` method on the `Leaf\Helpers\Authentication` class is a more advanced method for generating JWTs. It takes in 2 parameters:
+
+  - An array of claims to be added to the JWT
+  - The JWT secret string
+
+  ```php
+  use Leaf\Helpers\Authentication;
+
+  // ... your application code
+
+  Authentication::generateToken(
+      [
+          'user_id' => $userId,
+          'iat' => time(),
+          'iss' => 'localhost',
+          'exp' => time() + 3600,
+      ],
+      'MY_JWT_SECRET_STRING'
+  );
+  ```
+
+## Getting JWTs from the request
+
+Tokens from authenticated requests are usually sent in the `Authorization` header. Leaf Auth provides helpers that allow you directly pull in tokens from the request header.
+
+### Using the `getAuthorizationHeader` method
+
+Leaf Auth provides the `getAuthorizationHeader` helper method for getting the token from the request header. It returns null if no authorization header is found.
+
+```php
+use Leaf\Helpers\Authentication;
+
+$header = Authentication::getAuthorizationHeader();
+```
+
+### Using the `getBearerToken` method
+
+Leaf Auth provides the `getBearerToken` helper method for getting the token from the request header. It returns null if no bearer token is found.
+
+```php
+use Leaf\Helpers\Authentication;
+
+$token = Authentication::getBearerToken();
+```
+
+## Verifying JWTs
+
+Verifying JWTs is a very important step in the authentication process. Tokens can be tampered with, they can also expire, or be issued by an untrusted source. For this reason, you should always verify the token before using it.
+
+Leaf Auth provides 2 methods for verifying JWTs.
+
+- ### Using the `validateToken` method
+
+This method automatically checks if there is a token in the request header, and if there is, it verifies the token. It returns the decoded token if the token is valid, and returns false if the token is invalid.
+
+It takes in a single parameter, which is the JWT secret string. This secret string should be the same as the one used to generate the token.
+
+```php
+use Leaf\Helpers\Authentication;
+
+$data = Authentication::validateToken($secret);
+```
+
+Note that this method will automatically return false if there is no token in the request header. You can use the `errors` method to get the error message which is why the token validation failed.
+
+```php
+use Leaf\Helpers\Authentication;
+
+$data = Authentication::validateToken($secret);
+
+if (!$data) {
+    $errors = Authentication::errors();
+}
+```
+
+- ### Using the `validate` method
+
+Unlike the `validateToken` method, this method does not automatically check for a token in the request header. It takes in 2 parameters:
+
+- The token to be validated
+- The JWT secret string
+
+```php
+use Leaf\Helpers\Authentication;
+
+$token = Authentication::getBearerToken();
+$data = Authentication::validate($token, $secret);
+```
+
+Just like the `validateToken` method, this method returns the decoded token if the token is valid, and returns false if the token is invalid. You can use the `errors` method to get the error message which is why the token validation failed.
+
+```php
+use Leaf\Helpers\Authentication;
+
+$token = Authentication::getBearerToken();
+$data = Authentication::validate($token, $secret);
+
+if (!$data) {
+    $errors = Authentication::errors();
+}
+```

src/docs/auth/index.md

@@ -1 +1,97 @@
 # Authentication
+
+<!-- markdownlint-disable no-inline-html -->
+
+Numerous web applications offer their users a means to authenticate and access the application by "logging in." Adding this functionality to web applications can be a challenging and potentially dangerous task.
+
+Leaf provides a lightweight but very powerful authentication system to handle all the complexities of authentication in a few lines of code. We understand that authentication is a critical part of your application, so we've made it as simple and secure as possible.
+
+## Setting up
+
+You can install Leaf Auth using the Leaf CLI:
+
+::: code-group
+
+```bash:no-line-numbers [Leaf CLI]
+leaf install auth
+```
+
+```bash:no-line-numbers [Composer]
+composer require leafs/auth
+```
+
+:::
+
+The next step is to link your database and start signing users in.
+
+## Connecting to a database
+
+To do any kind of authentication, you need to connect to some kind of database which will store your users' data. If you are already using Leaf DB or Leaf MVC, then your database connection will automatically be used by Leaf Auth, so you don't need to connect to your database again.
+
+If you are not using Leaf DB or Leaf MVC, you can connect to your database manually:
+
+```php
+auth()->connect([
+  'dbtype' => '...',
+  'charset' => '...',
+  'port' => '...',
+  'host' => '...',
+  'dbname' => '...',
+  'user' => '...',
+  'password' => '...'
+]);
+```
+
+If you have an existing PDO connection, you can pass it to Leaf Auth:
+
+```php
+$db = new PDO('mysql:dbname=test;host=127.0.0.1', 'root', '');
+
+auth()->dbConnection($db);
+
+// you can use leaf auth the same way you always have
+```
+
+## Auth + Leaf MVC
+
+If you are using Leaf MVC, you can set up Leaf Auth to work with your default database connection by heading over to the `public/index.php` file and uncommenting the line that connects to the database:
+
+```php
+/*
+|--------------------------------------------------------------------------
+| Sync Leaf Db with ORM and connect
+|--------------------------------------------------------------------------
+|
+| Sync Leaf Db with ORM and connect to the database
+| This allows you to use Leaf Db without having
+| to initialize it in your controllers.
+|
+| If you want to use a different connection from those
+| used in your models, you can remove the line below and
+| add your own connection with:
+| db()->connect(...)
+|
+| **Uncomment the line below to use Leaf Db**
+| **You don't need this line to use Leaf Auth**
+*/
+// \Leaf\Database::initDb(); [!code --]
+\Leaf\Database::initDb(); // [!code ++]
+```
+
+That's all you need to do. Leaf Auth will automatically connect to your database using the details in your environment file. The auth configuration for your project can be found in the `config/auth.php` file. You can edit this file to change the configuration of Leaf Auth.
+
+## Database Considerations
+
+Leaf Auth doesn't give you any structure for your database, with that, you can structure your database in any way you prefer. However, there are some things you should note:
+
+1. By default, Leaf Auth assumes that your database primary key is `id`. If you have a database where you are using another field, say `admin_id` as the primary key, you will need to tell Leaf the name of your primary key. You can do this using the `ID_KEY` config:
+
+    ```php:no-line-numbers
+    auth()->config('id.key', 'admin_id');
+    ```
+
+2. Leaf Auth assumes that you will save your users in a database table named `users`, this might however not be the case for your application. If you want to use a different table, you can configure Leaf Auth using `db.table`:
+
+    ```php:no-line-numbers
+    auth()->config('db.table', 'admins');
+    ```