> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hana.leafphp.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Automatic token & auth state management

SPAs usually handle authentication via tokens, with checks to find if the token exists, and rugged middleware that maintains the current state or invalidates the state depending on responses from the backend.

Hana ships an authentication component powered by Hana Auth that automatically takes care of all of that. All you need to do is pass in your user, and Hana will take care of the rest.

<Accordion title="Install via npm">
  Hana Store is automatically added to projects generated using `create-hana-app`, but you can manually install it from npm

  ```bash theme={"theme":"ayu-dark"}
  npm install @hanabira/auth
  ```
</Accordion>

## **Getting started**

After installing Hana Auth, the first thing to do is to initialize your authentication using the `createAuth` function.

```tsx src/pages/_app.tsx theme={"theme":"ayu-dark"}
import { createAuth } from '@hanabira/auth';

createAuth();
```

This function takes in an optional config object that can be used to configure the auth utility. It is recommended to call this function in your root component so that it is only called once.

## **Auth Configuration**

The config object has the following properties:

* `tokenKey`: The key to use when saving the token to local storage. Defaults to `token`.
* `userKey`: The key to use when saving the user to local storage. Defaults to `user`.
* `refreshTokenKey`: The key to use when saving the refresh token to local storage. Defaults to `refreshToken`.
* `loginPath`: The path to redirect to when the user is not authenticated. Defaults to `/login`.
* `logoutPath`: The path to redirect to when the user logs out. Defaults to `/login`.
* `dashboardPath`: The path to redirect to when the user is authenticated. Defaults to `/dashboard`.
* `cookie`: Options to use when saving information to a cookie.

```tsx theme={"theme":"ayu-dark"}
import { createAuth } from '@hanabira/auth';

...

createAuth({
  tokenKey: 'token',
  userKey: 'user',
  refreshTokenKey: 'refreshToken',
  loginPath: '/login',
  dashboardPath: '/dashboard',
});
```

## **Authentication types**

The auth utility provides different types of authentication. These types are:

* `localstorage`: This type of authentication uses the browser's local storage to save the token and user information. This is the default type of authentication.
* `cookie`: This type of authentication uses cookies to save the token and user information.

Auth with local storage is the default type of authentication. To use cookie authentication, you need to pass in the `cookie` option to the `createAuth` function.

```tsx theme={"theme":"ayu-dark"}
import { createAuth } from '@hanabira/auth';

createAuth({
  cookie: {
    path: '/',
    expires: 60,
    domain: 'localhost',
    sameSite: 'Lax',
  },
});
```

The `cookie` option takes in the following properties:

* `path`: The path where the cookie is available. Defaults to `/`.
* `expires`: Define when the cookie will be removed. Value can be a Number which will be interpreted as days from time of creation or a Date instance. If omitted, the cookie becomes a session cookie.
* `domain`: Define the domain where the cookie is available. Defaults to the domain of the page where the cookie was created.
* `sameSite`: Asserts that a cookie must not be sent with cross-origin requests,providing some protection against cross-site request forgery attacks (CSRF)
* `secure`: A boolean indicating if the cookie transmission requires a secure protocol (https). Defaults to false.

From here, everything else is the same as local storage authentication.

## **Auth states**

Generally, there are two auth states: authenticated and unauthenticated. When the user is authenticated, the auth utility saves the token and user information to the appropriate storage. This information is then used to verify the auth state of the user and is removed when the user logs out. Hana Auth provides multiple ways to change and verify the auth state of the user.