Merge pull request #24 from gnk-softworks/next

Release PR 13/10/24

.editorconfig

@@ -0,0 +1,11 @@
+# https://EditorConfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

.github/workflows/pr.yml

@@ -8,25 +8,30 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
+      - name: Checkout repository
+        uses: actions/checkout@v4
 
       - name: Setup Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: '20'
 
       - name: Install dependencies
-        run: npm install
+        run: npm ci
 
       - name: Run Build
         run: npm run build
 
       - name: Run Coverage Script
         run: npm run coverage
 
+      - name: Markdownize Istanbul report
+        run: |
+          sed -i -e '1{/^----/d}; ${/^----/d}' ./coverage/report.txt
+
       - name: Comment Coverage on PR
+        if: ${{ ! github.event.pull_request.head.repo.fork }}
         uses: marocchino/sticky-pull-request-comment@v2
         with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          path: ./coverage/report.txt
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          path: ./coverage/report.txt

.github/workflows/publish_docs.yml

@@ -3,7 +3,7 @@ name: Publish docs
 on:
   push:
     branches:
-      - 'main'
+      - main
 
 permissions:
   contents: read
@@ -14,12 +14,13 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - name: setup actions
-        uses: actions/checkout@v3
+      - name: Checkout repository
+        uses: actions/checkout@v4
       - name: install malta
         run: |
           curl -o malta.tgz -L https://github.com/pilcrowonpaper/malta/releases/latest/download/linux-amd64.tgz
           tar -xvzf malta.tgz
+          rm malta.tgz
       - name: build
         working-directory: ./docs
         run: ../linux-amd64/malta build
@@ -37,4 +38,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v4

.github/workflows/publish_lib.yml

@@ -9,28 +9,31 @@ jobs:
   publish:
     runs-on: ubuntu-latest
 
+    if: "${{ !contains(github.event.head_commit.message, 'ci: publish version') }}"
+
     steps:
-      - name: Check out repository
-        uses: actions/checkout@v3
+      - name: Checkout repository
+        uses: actions/checkout@v4
 
       - name: Set up Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: '20'
           registry-url: 'https://registry.npmjs.org/'
 
       - name: Set Git user
         run: |
           git config user.name "narvik-publish-action"
-          git config user.email "[email protected]"
+          # https://api.github.com/users/github-actions%5Bbot%5D
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
       - name: Bump version
         run: npm version patch --no-git-tag-version
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Install dependencies
-        run: npm install
+        run: npm ci
 
       - name: Build package
         run: npm run build
@@ -47,5 +50,3 @@ jobs:
           git push
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-    if: "!contains(github.event.head_commit.message, 'ci: publish version')"

.npmignore

@@ -3,4 +3,5 @@
 /.github
 /coverage
 /dist/**/*.map
-*.log
+*.log
+/assets

README.md

@@ -4,7 +4,7 @@
 [![License: CC0-1.0](https://img.shields.io/badge/License-CC0%201.0-lightgrey.svg)](https://creativecommons.org/publicdomain/zero/1.0/)
 
 ## Introduction
-Narvik is a server side authentication library offering a simple API for managing sessions, independent of your chosen database setup. Built with TypeScript and released under the CC0 license, it provides flexibility and simplicity in handling authentication workflows.
+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.
 
@@ -23,7 +23,7 @@ npm i narvik
 
 ### Configuration
 
-The basic configuration requires only that you provide functions for managing session data in you data store.  
+The basic configuration requires only that you provide functions for managing session data in you data store.
 ```ts
 const narvik = new Narvik({
     data: {
@@ -43,17 +43,18 @@ const narvik = new Narvik({
 });
 ```
 
-You can also provide additional configuration options for sessions and cookies.  
+You can also provide additional configuration options for sessions and cookies.
 ```ts
 const narvik = new Narvik({
     data: {
         //as above
     },
-    session: { //Optional - Session configuration 
-        sessionExpiresInMs: 1000 * 60 * 60 * 24 * 7, //Optional - Desired session lenth in ms. Default is 30 Days - here value is 1 week
+    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
@@ -94,9 +95,8 @@ const blankCookie = narvik.createBlankSessionCookie();
 ## Further documentation an examples
 For more information on how to use Narvik, please refer to the [documentation](https://narvik-auth.com).
 
-## Features coming soon
-- [ ] Extend session interface to allow for custom attributes
-- [ ] Add ability to set session cookie to not expire
+## Feature requests and bug reports
+If you have a feature request or have found a bug, please create an issue on the [GitHub repository](https://github.com/gnk-softworks/narvik).
 
 ## Contributions
-If you want to improve the library, please create a pull request.
+If you want to contribute to the project please see the [contributing guide](https://narvik-auth.com/contributing).

docs/malta.config.json

@@ -22,16 +22,26 @@
     {
       "title": "Guides",
       "pages": [
-        ["Migrate from Lucia (Coming Soon)", "/guides/lucia"],
-        ["NextJS (Coming Soon)", "/guides/NextJS"]
+          ["Additional/Custom Session Data", "/guides/additional-session-data"],
+          ["Migrate from Lucia (Coming Soon)", "/guides/lucia"],
+          ["NextJS (Coming Soon)", "/guides/NextJS"]
       ]
     },
     {
       "title": "Miscellaneous",
       "pages": [
         ["Contributing", "/contributing"]
       ]
+    },
+    {
+      "title": "Links",
+      "pages": [
+        ["GitHub Repo", "https://github.com/gnk-softworks/narvik"],
+        ["NPM Package", "https://www.npmjs.com/package/narvik"],
+        ["Discord", "https://discord.gg/y2WGpuwztV"],
+        ["X", "https://x.com/NarvikAuth"]
+      ]
     }
   ],
   "asset_hashing": true
-}
+}

docs/pages/contributing/index.md

@@ -17,11 +17,12 @@ Narvik is an open-source project under a cc0 license, and we welcome any contrib
    - Features: Before any new feature is merged it must be approved by maintainers in GitHub Issues. We will review and approve features based on their complexity and alignment with the project goals.
 
 ## Become a Maintainer
-If you are interested in becoming a maintainer for the project, please make a number of contributions to the project first then reach out.
+If you are interested in becoming a maintainer for the project, please make a number of contributions to the project first then reach out on the Discord server to express your interest.
 
 ## Code of Conduct
 Don't be a jerk. We are all here to learn and improve the project. Please be respectful of others and their contributions.
 
 ## Useful Links
 - [GitHub Repository](https://github.com/gnk-softworks/narvik)
-- [NPM Package](https://www.npmjs.com/package/narvik)
+- [NPM Package](https://www.npmjs.com/package/narvik)
+- [Discord](https://discord.gg/y2WGpuwztV)

docs/pages/documentation/cookies.md

@@ -11,6 +11,8 @@ The `createSessionCookie` function takes a session token and returns a cookie ob
 const cookie = narvik.createSessionCookie(sessionToken);
 ```
 
+> Note: By default, the `Max Age` attribute is set to match the session expiry time. If you need the cookie to expire at a different time, you can configure this by setting the `cookieExpiresInMs` option in the Narvik config. This is particularly helpful if your framework doesn’t allow you to set or update the cookie in all locations where you validate and extend the session.
+
 ### createBlankSessionCookie()
 The `createBlankSessionCookie` function returns a blank cookie object that can be used to easily clear a session cookie in your framework of choice.
 ```ts
@@ -20,13 +22,21 @@ const blankCookie = narvik.createBlankSessionCookie();
 ## Cookie Object
 The cookie object is a straightforward structure containing a name, value, and attributes, which can be used to set a cookie. The attributes mirror those available when setting cookies.
 
-Note: A serialize function will be added to the cookie object in the future, simplifying the process of setting cookies outside of your framework.
-
 ```ts
-export interface Cookie {
-    name: string;
-    value: string;
-    attributes: CookieAttributes;
+export class Cookie {
+    public name: string;
+    public value: string;
+    public attributes: CookieAttributes;
+
+    constructor(name: string, value: string, attributes: CookieAttributes) {
+        this.name = name;
+        this.value = value;
+        this.attributes = attributes;
+    }
+
+    public serialize(): string {
+        return cookies.serialize(this.name, this.value, this.attributes);
+    }
 }
 
 export interface CookieAttributes {
@@ -37,4 +47,13 @@ export interface CookieAttributes {
     sameSite?: "none" | "lax" | "strict";
     maxAge?: number;
 }
-```
+```
+
+The `serialize` method is used to convert the cookie object into a string that can be set as a cookie using 'Set-Cookie' headers.
+```ts
+const cookie = narvik.createSessionCookie(sessionToken);
+const cookieString = cookie.serialize();
+
+// Set the cookie in the response headers
+res.setHeader('Set-Cookie', cookieString);
+```

docs/pages/documentation/sessions.md

@@ -15,8 +15,9 @@ interface Session {
 }
 ```
 
-## Creating Sessions
+> Note: For information on how to extend the session object with additional data, see the [Additional Session Data](/guides/additional-session-data) guide.
 
+## Creating Sessions
 To create a session, call the `createSession()` function with the authenticated user’s ID. This will generate a session object and a token, the session is then saved to your database via the saveSession callback provided in your configuration. The `createSession()` function returns a CreateSessionResult object containing both the session object and the token. The token can be stored as a cookie ([see the cookies section](/documentation/cookies)) or be passed in as a token on subsequent requests to identify the user .
 ```ts
 export interface CreateSessionResult {
@@ -41,8 +42,8 @@ The session’s expiresAt field is automatically extended with each use, ensurin
 ```ts
 export const narvik = new Narvik({
     data: {}, //data configuration
-    session: { //Optional - Session configuration 
-        sessionExpiresInMs: 1000 * 60 * 60 * 24 * 7, //Optional - Desired session lenth in ms. Default is 30 Days - here value is 1 week
+    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
 });
@@ -80,4 +81,4 @@ await narvik.invalidateSession(sessionId);
 For management of sessions in your database, you should implement the following functions for use in other places in your application:
 - Get all sessions for a user - Useful for showing a user all of their active sessions
 - Delete sessions for a user - Useful for when a user changes their password
-- Delete all expired sessions - Useful for cleaning up your database although some databases have built-in TTL functionality which can be used instead.
+- Delete all expired sessions - Useful for cleaning up your database although some databases have built-in TTL functionality which can be used instead.

docs/pages/getting-started/setup.md

@@ -41,11 +41,12 @@ export const narvik = new Narvik({
     data: {
         //as above
     },
-    session: { //Optional - Session configuration 
-        sessionExpiresInMs: 1000 * 60 * 60 * 24 * 7, //Optional - Desired session lenth in ms. Default is 30 Days - here value is 1 week
+    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 - Default true - set to true for https, set to false for http
             domain: "example.com", //Optional - Domain attribute. Default is not set
@@ -56,6 +57,4 @@ export const narvik = new Narvik({
 });
 ```
 
-
-
 #### [Next Section: Usage](/getting-started/usage)