npm package: @hirameki-erp/auth
Description: Install the package:
Author: Mark Terence Tiglao
Latest version: 0.2.4

# ERP Auth

## Manual Installation

Install the package:

```bash
pnpm install @hirameki-erp/auth
```

### Database Setup

ERP Auth uses Kysely for database interactions. You need to set up a connection config for Kysely in your application.

Follow the Kysely CLI configuration guide to set up your database connection: [Kysely CLI Configuration](https://github.com/kysely-org/kysely-ctl/tree/main?tab=readme-ov-file#configuration).

Then, run the auth migration command to create the necessary tables for ERP Auth:

The `-c` option is required. It should point to your Kysely configuration file that connects to your database.

```bash
pnpm exec hirameki-auth migrate:latest -c .config/kysely.config.ts
```

Migration should create a table named `erp_user`, `erp_account` and `erp_session` tables along with `_erp_auth_migrations` table and the lock table dedicated for ERP Auth in your database.

### Application Setup

Define `AUTH_ENDPOINT` environment variable in your `.env` file:

Make sure your application can load environment variables.

```ini
AUTH_ENDPOINT="http://localhost:3000/auth"
```

Call the setup function in your application entry point:

This is necessary to set the base URL for the auth HTTP client.

```ts
import { setup as setupErpAuth } from '@hirameki-erp/auth';
setupErpAuth();
```

Next, setup the HTTP middleware in your Express application:

Make sure to place the ERP Auth middleware before your route handlers and after any parsing middleware like `body-parser`, cors, cookie-parser, etc.

```ts
import { erpAuth } from '@hirameki-erp/auth';

app.use(bodyParser.json());

app.use(erpAuth());

// Your route handlers go here
app.use(errorHandlerMiddleware());
```

## Endpoints

Once the ERP Auth plugin is set up, it exposes the following endpoints:

- `POST /auth/login` - Login endpoint
- `POST /auth/addUser` - Add User endpoint
- `GET /auth/getUser` - Get User endpoint

In most cases, if you don't want to expose the `/addUser` endpoint publicly, you can disable it for now by creating a custom middleware that restricts access to it in your Express application.

```ts
// Disable Add User Endpoint. Place this before erpAuth middleware
app.use('/auth/addUser', (req, res, next) => {
  res.status(404).send('not found');
});

app.use(erpAuth());
```

## API

Erp Auth exposes some utils and Axios HTTP client for making requests to the auth service if needed.

> NOTE: The plugin does not export an ORM or database client to interact with the tables created by the migration. You need to set up your own Database client using any other ORM or query builder of your choice to interact with the `erp_user`, `erp_account` and `erp_session` tables.

**Http Client**

```ts
import { api as erpAuthApi } from '@hirameki-erp/auth';

// Add User Endpoint
erpAuthApi.addUser(data)

// Login Endpoint
erpAuthApi.login(data)

// Axios HTTP Client
erpAuthApi.erpAuthHttpClient
```

## Database Schema

Here is a table summarizing the schema for each table defined in the migration:

### erp_user

User table for the consumer application to store user profile information fetched from the auth-server. No passwords or sensitive information is stored here, just metadata.

| Column      | Type         | Constraints / Notes                                                                                  |
|-------------|--------------|-----------------------------------------------------------------------------------------------------|
| id          | varchar(36)  | PK, Unique, Not Null, Comment: ID of user from auth-server                                          |
| first_name  | text         | Not Null                                                                                            |
| last_name   | text         |                                                                                                     |
| email       | varchar(320) | Not Null                                                                                            |
| image       | LONGTEXT     | Comment: store profile image as base64 string (192x192 px, transformed by auth-server)              |
| image_url   | text         | Comment: External URL hosted by auth server, may be blocked/slow/CORS issues                        |
| createdAt   | datetime     | Not Null                                                                                            |
| updatedAt   | datetime     | Not Null                                                                                            |

---

### erp_account

A table that contains provider account information for users (Not accepting oauth providers yet.). 

Example: a field providerId always defaults to `auth-server` meaning the account is from our own auth-server. This has accessToken, refreshToken, accessTokenExpiresAt field.

| Column               | Type         | Constraints / Notes                                         |
|----------------------|--------------|-------------------------------------------------------------|
| id                   | varchar(36)  | PK, Not Null                                                |
| accountId            | text         | Not Null, Comment: accountId from external provider         |
| providerId           | text         | Not Null, Comment: providerId from external provider        |
| userId               | varchar(36)  | Not Null, FK to erp_user.id                                 |
| accessToken          | text         |                                                             |
| refreshToken         | text         |                                                             |
| accessTokenExpiresAt | datetime     |                                                             |
| refreshTokenExpiresAt| datetime     |                                                             |
| scope                | text         |                                                             |
| createdAt            | datetime     | Not Null                                                    |
| updatedAt            | datetime     | Not Null                                                    |
| deletedAt            | datetime     |                                                             |

---

### erp_session

The session table store session info of users logged in from the consuming application to the auth-server.
This manages session of the user on the consuming application side, we can safely assume that once the user is on the `erp_user` table, they are authenticated/registered, even if the `accessToken` in the `erp_account` table has expired (only for when providerId is from our own auth-server).

This way this app can have it's own session management. 

| Column     | Type         | Constraints / Notes         |
|------------|--------------|----------------------------|
| id         | varchar(36)  | PK, Not Null               |
| userId     | varchar(36)  | Not Null, FK to erp_user.id|
| expiresAt  | datetime     | Not Null                   |
| createdAt  | datetime     | Not Null                   |