Narvik Auth

Introduction

Narvik is a server side authentication library that abstracts away the complexity of managing sessions using an API that's easy to use, understand, and extend. It works independent of your chosen database setup, is built with TypeScript and released under the CC0 license.

Although developed from scratch, Narvik draws inspiration from version 3 of the Lucia authentication library (https://lucia-auth.com), incorporating several ideas and tools developed by @PilcrowOnPaper.

Installation

npm i narvik

or for the jsr.io package

npx jsr add @narvik/narvik

Features

• [x] Simple, easy to understand configuration
• [x] Data store agnostic
• [x] Works in any runtime
• [x] Fully typed

Usage

Configuration

The basic configuration requires only that you provide functions for managing session data in you data store.

const narvik = new Narvik({
    data: {
        saveSession: async (session: Session): Promise<void> => {
            // Save the session to your database
        },
        fetchSession: async (sessionId: string): Promise<Session | null>  => {
            // Fetch the session from your database
        },
        updateSessionExpiry: async (sessionId: string, updateExpiresAt: Date): Promise<void>  => {
            // Update the session expiry in your database
        },
        deleteSession: async (sessionId: string): Promise<void>  => {
            // Delete the session from your database
        }
    },
});

You can also provide additional configuration options for sessions and cookies.

const narvik = new Narvik({
    data: {
        //as above
    },
    session: { //Optional - Session configuration
        sessionExpiresInMs: 1000 * 60 * 60 * 24 * 7, //Optional - Desired session length in ms. Default is 30 Days - here value is 1 week
    },
    cookie: { //Optional - Cookie configuration
        name: "your-app-session", //Optional - Session cookie name. Default is "narvik_session"
        cookieExpiresInMs: 1000 * 60 * 60 * 24 * 7, //Optional - Desired cookie length in ms. Default is same as "sessionExpiresInMs" - here value is 1 week
        attributes: {
            secure: true, //Optional - Secure attribute. Default is true
            domain: "example.com", //Optional - Domain attribute. Default is not set
            path: "/", //Optional - Path attribute. Default is "/"
            sameSite: "lax", //Optional - SameSite attribute. Default is "lax"
        }
    }
});

Usage

//Your user who has passed authentication
const authenticatedUser = {
    id: "123",
    name: "John Smith",
    email: "[email protected]"
};

//Create a new session for the authenticated user
const createSessionReult = await narvik.createSession(authenticatedUser.id);

//Create a cookie to store the session
const cookie = narvik.createSessionCookie(createSessionReult.token);
cookies().set(cookie.name, cookie.value, cookie.attributes);

//Fetch the session from the database
const sessionToken = cookies().get(narvik.cookieName)?.value ?? null;
if(!sessionToken) {
    // Do something if the session is not found
}
const validatedSession = await narvik.validateSession(sessionToken); //Returns Session if valid or null if session is invalid

//Create a blank cookie to clear the session
const blankCookie = narvik.createBlankSessionCookie();

Further documentation an examples

For more information on how to use Narvik, please refer to the documentation.

Feature requests and bug reports

If you have a feature request or have found a bug, please create an issue on the GitHub repository.

Contributions

If you want to contribute to the project please see the contributing guide.

Community

Join the Narvik community on Discord.