Merge branch 'feature/bslt-132' into develop

Author: Necrelox

.npmignore

@@ -7,8 +7,6 @@
 
 # === Archives and build-related files ===
 *.tgz
-bun.lockb
-pnpm-lock.yaml
 
 # === Bundler configuration files ===
 bundler.ts
@@ -26,7 +24,7 @@ jest.config.json
 node_modules/
 package-lock.json
 yarn.lock
-bun.lockb
+bun.lock
 pnpm-lock.yaml
 
 # === Project-specific folders ===

README.md

@@ -5,14 +5,16 @@
 - [📦 Basalt-auth](#-basalt-auth)
   - [📌 Table of contents](#-table-of-contents)
   - [📝 Description](#-description)
-  - [🌟 Documentation](#-documentation)
+  - [🌟 Documentation](#-Documentation)
   - [🔧 Installation](#-installation)
   - [⚖️ License](#️-license)
   - [📧 Contact](#-contact)
 
 ## 📝 Description
 
-`Basalt-auth` is a library designed to create a secure and user-friendly authentication system.  
+> ONLY FOR BUN
+
+**Basalt-auth** is a library designed to create a secure and user-friendly authentication system.  
 It is inspired by [JSON Web Tokens (JWT)](https://jwt.io/), with some differences.
 
 One of the main differences of `Basalt-auth` is the key management: instead of using a global secret key, it generates a unique key pair for each token, thereby increasing the security of the individual session.
@@ -28,14 +30,8 @@ Only the public key and the token are stored, ensuring that interactions remain
 
 ## 🔧 Installation
 
-NPM:
-```bash
-npm i @basalt-lab/basalt-auth
-```
-
-PNPM:
 ```bash
-pnpm i @basalt-lab/basalt-auth
+bun add @basalt-lab/basalt-auth
 ```
 
 ## ⚖️ License

bun.lock

@@ -7,7 +7,7 @@ const devDependencies = 'devDependencies' in pkg ? Object.keys(pkg.devDependenci
 const peerDependencies = 'peerDependencies' in pkg ? Object.keys(pkg.peerDependencies ?? {}) : [];
 
 await Bun.build({
-    target: 'node',
+    target: 'bun',
     external: [...dependencies, ...devDependencies, ...peerDependencies],
     root: './source',
     entrypoints: [

bun.lockb

@@ -1,8 +1,9 @@
 {
   "name": "@basalt-lab/basalt-auth",
   "version": "1.9.4",
-  "description": "Authentication module for Basalt Framework",
+  "description": "A sample authentication library each token has key pair (public and private)",
   "keywords": [
+    "bun",
     "basalt-auth",
     "basalt",
     "auth",
@@ -39,18 +40,18 @@
     "lint": "eslint ./source"
   },
   "devDependencies": {
-    "@eslint/js": "^9.17.0",
-    "@stylistic/eslint-plugin": "^2.12.1",
-    "@types/bun": "^1.1.15",
-    "@types/node": "^22.10.5",
+    "@eslint/js": "^9.18.0",
+    "@stylistic/eslint-plugin": "^2.13.0",
+    "@types/bun": "^1.2.0",
     "bun-plugin-dts": "^0.3.0",
+    "eslint": "^9.18.0",
     "eslint-plugin-tsdoc": "^0.4.0",
-    "eslint": "^9.17.0",
-    "typescript-eslint": "^8.19.1",
-    "typedoc": "^0.27.6"
+    "globals": "^15.14.0",
+    "typedoc": "^0.27.6",
+    "typescript-eslint": "^8.21.0"
   },
   "peerDependencies": {
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.3"
   },
   "changelog": {
     "types": {

bundler.ts

@@ -1,4 +1,5 @@
-import { randomUUID, sign as sig, verify as ver } from 'crypto';
+import { randomUUIDv7 } from 'bun';
+import { sign as sig, verify as ver } from 'crypto';
 
 import { BasaltError } from '#/error/basaltError';
 import { GLOBAL_KEY_ERROR } from '#/error/key/globalKeyError';
@@ -90,8 +91,8 @@ function _buildSignature(header: string, payload: string, privateKey: string, pa
  *
  * @param token - The authentication token.
  *
- * @throws ({@link BasaltError}) If the token structure is invalid. ({@link GLOBAL_KEY_ERROR}.TOKEN_INVALID_STRUCTURE)
- * @throws ({@link BasaltError}) If the token header is invalid. ({@link GLOBAL_KEY_ERROR}.TOKEN_INVALID_HEADER)
+ * @throws ({@link BasaltError}) If the token structure is invalid. ({@link GLOBAL_KEY_ERROR.TOKEN_INVALID_STRUCTURE})
+ * @throws ({@link BasaltError}) If the token header is invalid. ({@link GLOBAL_KEY_ERROR.TOKEN_INVALID_HEADER})
  *
  * @returns The parsed header of the token. ({@link BasaltTokenHeader})
  */
@@ -117,7 +118,7 @@ function getHeader(token: string): BasaltTokenHeader {
  *
  * @param token - The authentication token.
  *
- * @throws ({@link BasaltError}) If the token structure is invalid. ({@link GLOBAL_KEY_ERROR}.TOKEN_INVALID_STRUCTURE)
+ * @throws ({@link BasaltError}) If the token structure is invalid. ({@link GLOBAL_KEY_ERROR.TOKEN_INVALID_STRUCTURE})
  *
  * @returns The UUID of the token.
  */
@@ -130,7 +131,7 @@ function getTokenUuid(token: string): string {
  *
  * @param token - The authentication token.
  *
- * @throws ({@link BasaltError}) If the token structure is invalid. ({@link GLOBAL_KEY_ERROR}.TOKEN_INVALID_STRUCTURE)
+ * @throws ({@link BasaltError}) If the token structure is invalid. ({@link GLOBAL_KEY_ERROR.TOKEN_INVALID_STRUCTURE})
  *
  * @returns The expiration date of the token.
  */
@@ -143,7 +144,7 @@ function getExpirationDate(token: string): Date {
  *
  * @param token - The authentication token.
  *
- * @throws ({@link BasaltError}) If the token structure is invalid. ({@link GLOBAL_KEY_ERROR}.TOKEN_INVALID_STRUCTURE)
+ * @throws ({@link BasaltError}) If the token structure is invalid. ({@link GLOBAL_KEY_ERROR.TOKEN_INVALID_STRUCTURE})
  *
  * @returns The intended audience of the token.
  */
@@ -156,7 +157,7 @@ function getAudience(token: string): string {
  *
  * @param token - The authentication token.
  *
- * @throws ({@link BasaltError} If the token structure is invalid. ({@link GLOBAL_KEY_ERROR}.TOKEN_INVALID_STRUCTURE)
+ * @throws ({@link BasaltError} If the token structure is invalid. ({@link GLOBAL_KEY_ERROR.TOKEN_INVALID_STRUCTURE})
  *
  * @returns The issuer of the token.
  */
@@ -171,8 +172,8 @@ function getIssuer(token: string): string {
  *
  * @param token - The authentication token.
  *
- * @throws ({@link BasaltError}) If the token structure is invalid. ({@link GLOBAL_KEY_ERROR}.TOKEN_INVALID_STRUCTURE)
- * @throws ({@link BasaltError}) If the token payload is invalid. ({@link GLOBAL_KEY_ERROR}.TOKEN_INVALID_PAYLOAD)
+ * @throws ({@link BasaltError}) If the token structure is invalid. ({@link GLOBAL_KEY_ERROR.TOKEN_INVALID_STRUCTURE})
+ * @throws ({@link BasaltError}) If the token payload is invalid. ({@link GLOBAL_KEY_ERROR.TOKEN_INVALID_PAYLOAD})
  *
  * @returns The parsed payload of the token. ({@link T})
  */
@@ -198,7 +199,7 @@ function getPayload<T extends object>(token: string): T {
  *
  * @param token - The authentication token.
  *
- * @throws ({@link BasaltError}) If the token structure is invalid. ({@link GLOBAL_KEY_ERROR}.TOKEN_INVALID_STRUCTURE)
+ * @throws ({@link BasaltError}) If the token structure is invalid. ({@link GLOBAL_KEY_ERROR.TOKEN_INVALID_STRUCTURE})
  *
  * @returns True if the token has expired, false otherwise.
  */
@@ -237,7 +238,7 @@ function sign<T extends object>(
     issuer = 'Basalt-Issuer',
     audience = 'Basalt-Audience'
 ): BasaltTokenSignResult {
-    const tokenUUid: string = randomUUID();
+    const tokenUUid: string = randomUUIDv7();
     const keyPair: KeyPairED25519 = generateKeyPairED25519();
 
     const headerStringify: string = _buildHeader(tokenUUid, expirationMs, issuer, audience);
@@ -257,9 +258,9 @@ function sign<T extends object>(
  * @param token - The authentication token to verify.
  * @param publicKey - The public key corresponding to the private key used to sign the token.
  *
- * @throws ({@link BasaltError}) If the token structure is invalid. ({@link GLOBAL_KEY_ERROR}.TOKEN_INVALID_STRUCTURE)
- * @throws ({@link BasaltError}) If the token has expired. ({@link GLOBAL_KEY_ERROR}.TOKEN_IS_EXPIRED)
- * @throws ({@link BasaltError}) If the token signature is invalid. ({@link GLOBAL_KEY_ERROR}.TOKEN_SIGNATURE_INVALID)
+ * @throws ({@link BasaltError}) If the token structure is invalid. ({@link GLOBAL_KEY_ERROR.TOKEN_INVALID_STRUCTURE})
+ * @throws ({@link BasaltError}) If the token has expired. ({@link GLOBAL_KEY_ERROR.TOKEN_IS_EXPIRED})
+ * @throws ({@link BasaltError}) If the token signature is invalid. ({@link GLOBAL_KEY_ERROR.TOKEN_SIGNATURE_INVALID})
  */
 function verify(token: string, publicKey: string): void {
     if (isExpired(token))

package.json

@@ -1,4 +1,4 @@
-import { randomUUID } from 'crypto';
+import { randomUUIDv7 } from 'bun';
 
 /**
  * Represents the options for the Basalt error.
@@ -7,7 +7,7 @@ export interface BasaltErrorOptions<T = unknown> {
     /**
      * The error key.
      */
-    key?: [string, number] | undefined;
+    key?: readonly [string, number] | undefined;
     /**
      * The cause of the error.
      */
@@ -17,7 +17,7 @@ export interface BasaltErrorOptions<T = unknown> {
 /**
  * Basalt error class that extends the ({@link Error}) class and provides additional properties. (uuidError, date, code, fileName, line, column)
  *
- * @typeparam T - The type of the cause of the error.
+ * @typeParam T - The type of the cause of the error.
  *
  * @example
  * The following example demonstrates how to throw a new instance of the Basalt error.
@@ -27,29 +27,33 @@ export interface BasaltErrorOptions<T = unknown> {
  * } catch (error) {
  *  console.log(error instanceof BasaltError); // true
  *  console.log(error instanceof Error); // true
- *  // u can access to uuidError, date, code, fileName, line, column, message, name, stack, cause
+ *  // u can access to uuidError, date, code, fileName, line, column, message, name, stack, cause, toJSON
  * }
  * ```
  * @example
  * The following example demonstrates how to create a new instance of the Basalt error with provided type for the cause.
  * ```typescript
+ * // { foo: 'bar' } is the type of the cause;
  * const basaltError: BasaltError<{ foo: 'bar' }> = new BasaltError({
  *     key: 'error.unknown',
  *     cause: {
  *         foo: 'bar',
  *     },
  * });
- * console.log(basaltError.cause); // { foo: 'bar' } if you make ctrl + space after cause. you will see the properties of the cause
+ * console.log(basaltError.cause); // { foo: 'bar' }
  * ```
  */
-export class BasaltError<T = unknown> extends Error {
+export class BasaltError<const T = unknown> extends Error {
+    /**
+     * The cause of the error. (if available)
+     */
     public override readonly cause: T | undefined;
 
     /**
      * The unique identifier of the error.
      * This identifier is used to track the error in the logs.
      */
-    private readonly _uuidError: string = randomUUID();
+    private readonly _uuid: string = randomUUIDv7();
 
     /**
      * The date when the error was created.
@@ -86,57 +90,83 @@ export class BasaltError<T = unknown> extends Error {
         super.name = 'BasaltError';
         this.cause = basaltErrorOptions?.cause;
         this._code = basaltErrorOptions?.key?.[1] || 500;
-        if (Error.captureStackTrace) {
-            Error.captureStackTrace(this, this.constructor);
-            const stackLine = this.stack?.split('\n')[1]?.trim();
-            const match = stackLine?.match(/:(\d+):(\d+)\)$/);
-            this._fileName = stackLine?.split('(')[1]?.split(':')[0] || '';
-            if (match) {
-                this._line = match[1] ? parseInt(match[1], 10) : 0;
-                this._column = match[2] ? parseInt(match[2], 10) : 0;
-            }
+        const stackLine = this.stack?.split('\n')[1]?.trim();
+        const match = stackLine?.match(/\(?(.+):(\d+):(\d+)\)?$/);
+        if (match) {
+            this._fileName = match[1] || '';
+            this._line = parseInt(match[2], 10) || 0;
+            this._column = parseInt(match[3], 10) || 0;
         }
     }
 
     /**
-     * Gets the unique identifier of the error.
+     * The unique identifier of the error.
      */
-    public get uuidError(): string {
-        return this._uuidError;
+    public get uuid(): string {
+        return this._uuid;
     }
 
     /**
-     * Gets the date when the error was created.
+     * The date when the error was created.
      */
     public get date(): Date {
         return this._date;
     }
 
     /**
-     * Gets the fileName where the error occurred (if available).
+     * The error code. (HTTP status code)
+     */
+    public get code(): number {
+        return this._code;
+    }
+
+    /**
+     * The fileName where the error occurred (if available).
      */
     public get fileName(): string {
         return this._fileName;
     }
 
     /**
-     * Gets the line number where the error occurred (if available).
+     * The line number where the error occurred (if available).
      */
     public get line(): number {
         return this._line;
     }
 
     /**
-     * Gets the column number where the error occurred (if available).
+     * The column number where the error occurred (if available).
      */
     public get column(): number {
         return this._column;
     }
 
     /**
-     * Gets the error code.
+     * Converts the error object to a JSON object.
+     *
+     * @returns The error object as a JSON object.
      */
-    public get code(): number {
-        return this._code;
+    public toJSON(): {
+        name: string;
+        uuid: string;
+        date: Date;
+        message: string;
+        code: number;
+        cause: T | undefined;
+        fileName: string;
+        line: number;
+        column: number;
+    } {
+        return {
+            name: this.name,
+            uuid: this._uuid,
+            date: this._date,
+            message: this.message,
+            code: this._code,
+            cause: this.cause,
+            fileName: this._fileName,
+            line: this._line,
+            column: this._column
+        };
     }
 }

source/core/basaltToken.ts

@@ -1,7 +1,7 @@
 /**
  * Global error key is a list of errors in the global context.
  */
-export const GLOBAL_KEY_ERROR: Record<string, [string, number]> = {
+export const GLOBAL_KEY_ERROR = {
     TOKEN_INVALID_STRUCTURE: ['error.basalt-auth.token_invalid_structure', 401],
     TOKEN_INVALID_HEADER: ['error.basalt-auth.token_invalid_header', 401],
     TOKEN_INVALID_PAYLOAD: ['error.basalt-auth.token_invalid_payload', 401],

source/error/basaltError.ts

@@ -1,4 +1,5 @@
-import { generateKeyPairSync, randomUUID, type KeyPairSyncResult } from 'crypto';
+import { generateKeyPairSync, type KeyPairSyncResult } from 'crypto';
+import { randomUUIDv7 } from 'bun';
 
 import type { KeyPairED25519 } from '#/types/data/keyPairED25519';
 
@@ -8,7 +9,7 @@ import type { KeyPairED25519 } from '#/types/data/keyPairED25519';
  * @returns The generated key pair with the passphrase. ({@link KeyPairED25519})
  */
 export function generateKeyPairED25519(): KeyPairED25519 {
-    const passphrase: string = randomUUID();
+    const passphrase: string = randomUUIDv7();
     const keyPair: KeyPairSyncResult<string, string> = generateKeyPairSync(
         'ed25519',
         {