authentication-core-lib 0.1.0

package/README.md

@@ -0,0 +1,240 @@
+# authentication-core-lib
+
+A small, framework-agnostic authentication library for TypeScript.
+
+The library is intentionally designed without a fixed database layer. It only provides the core logic for:
+
+- registration
+- login
+- resolving the current user from a JWT
+- error classes and DTOs
+
+Persistence, user lookup, and user creation are connected from the outside via callback functions. This allows you to use the library with an in-memory store, a JSON file, a custom API, or a database.
+
+## Features
+
+- Password hashing with argon2id
+- JWT-based authentication
+- Active user validation
+- Registration validation
+- Email notification after successful registration
+- Clear separation between core logic and persistence
+
+## Project structure
+
+```text
+src/
+	current-user.ts   # Verify JWTs and validate active users
+	errors.ts         # Central error classes
+	interfaces.ts     # Shared types and DTOs
+	login.ts          # Login logic
+	register.ts       # Registration logic
+```
+
+## Installation
+
+The library expects the following runtime dependencies:
+
+- argon2
+- jsonwebtoken
+- nodemailer
+
+You will typically also want TypeScript.
+
+```bash
+npm install argon2 jsonwebtoken nodemailer
+npm install -D typescript @types/node
+```
+
+## Quick start
+
+### 1. Provide a user store
+
+The login and registration logic works with a `FetchedUser` object and callback functions. For example, you can build an in-memory store:
+
+```ts
+import { AuthenticationCoreLogin } from './src/login.ts'
+import { AuthenticationCoreRegister } from './src/register.ts'
+import { AuthenticationCoreCurrentUser } from './src/current-user.ts'
+import type {
+	FetchedUser,
+	RegistrationInputData,
+	VerificationMail,
+	MailTransportConfig,
+} from './src/interfaces.ts'
+
+const users = new Map<string, FetchedUser>()
+```
+
+### 2. Registration
+
+The following callbacks belong to the registration flow:
+
+```ts
+async function mailExistsRoutine(mail: string): Promise<boolean> {
+	return users.has(mail)
+}
+
+async function dataProcessing(
+	identification: string,
+	hashedPassword: string,
+	customInputData: Record<string, unknown>
+): Promise<FetchedUser> {
+	const user: FetchedUser = {
+		uuid: crypto.randomUUID(),
+		mail: identification,
+		password: hashedPassword,
+		isActive: false,
+		...customInputData,
+	} as FetchedUser
+
+	users.set(identification, user)
+	return user
+}
+```
+
+```ts
+const registrationInputData: RegistrationInputData = {
+	typedMail: 'demo@example.com',
+	typedPassword: 'secret-password',
+	typedPasswordRepeated: 'secret-password',
+}
+
+const verificationMail: VerificationMail = {
+	from: 'no-reply@example.com',
+	subject: 'Verify your account',
+	content: (uuid: string) => `https://example.com/verify?uuid=${uuid}`,
+}
+
+const mailTransportConfig: MailTransportConfig = {
+	host: '127.0.0.1',
+	port: 1025,
+	secure: false,
+	auth: {
+		user: '',
+		pass: '',
+	},
+}
+
+const newUser = await AuthenticationCoreRegister.register(
+	registrationInputData,
+	mailExistsRoutine,
+	{},
+	dataProcessing,
+	verificationMail,
+	mailTransportConfig,
+)
+```
+
+### 3. Login
+
+```ts
+const token = await AuthenticationCoreLogin.login(
+	'demo@example.com',
+	'secret-password',
+	users.get('demo@example.com'),
+	'your-jwt-secret'
+)
+```
+
+### 4. Resolve the current user
+
+The following callback belongs to the current-user flow:
+
+```ts
+async function isActiveCallback(uuid: string): Promise<boolean> {
+	for (const user of users.values()) {
+		if (user.uuid === uuid) {
+			return user.isActive
+		}
+	}
+
+	return false
+}
+```
+
+```ts
+const userUuid = await AuthenticationCoreCurrentUser.getCurrentUser(
+	token,
+	'your-jwt-secret',
+	isActiveCallback,
+)
+```
+
+## API overview
+
+### `AuthenticationCoreLogin.login(...)`
+
+Checks mail and password, validates the user status, and generates a JWT.
+
+**Parameters:**
+
+- `typedMail`: email address
+- `typedPassword`: plaintext password
+- `fetchedUser`: already loaded user or `undefined`
+- `jwtKey`: JWT secret
+- `jwtOptions`: optional JWT options
+
+**Returns:** JWT as a string
+
+### `AuthenticationCoreRegister.register(...)`
+
+Validates registration input, checks whether the mail address is already taken, hashes the password, and sends a verification email after successful persistence.
+
+**Parameters:**
+
+- `registrationInputData`: mail, password, and password confirmation
+- `mailExistsRoutine`: callback for mail lookup
+- `customInputData`: additional user data
+- `dataProcessing`: callback for storing the new user
+- `verificationMail`: verification email configuration
+- `mailTransportConfig`: SMTP configuration
+- `hashOptions`: argon2 options
+
+**Returns:** the stored user
+
+### `AuthenticationCoreCurrentUser.getCurrentUser(...)`
+
+Verifies a JWT, reads the user ID from `sub`, and checks whether the user is active.
+
+**Parameters:**
+
+- `token`: JWT
+- `jwtKey`: secret or public key
+- `isActiveCallback`: callback for active-user lookup
+- `verifyOptions`: optional JWT verification options
+
+**Returns:** the current user's UUID
+
+## Error classes
+
+The library provides custom error classes with `code` and `statusCode`:
+
+- `AuthError`
+- `InvalidCredentialsError`
+- `UserInactiveError`
+- `InvalidTokenError`
+- `MailTakenError`
+- `PasswordMismatchError`
+
+This makes it easy to handle errors cleanly in your API or UI.
+
+## Important notes
+
+- The library does not include a fixed database integration.
+- Persistence is fully provided through callbacks.
+- For production, use a strong JWT secret key.
+- For registration emails, use a real SMTP configuration.
+- `argon2.verify()` expects the stored hash first and the plaintext password second.
+
+## Example for custom persistence
+
+You can easily connect the library to a database, a REST service, or an in-memory store. The only things you need are suitable implementations for:
+
+- `mailExistsRoutine`
+- `dataProcessing`
+- `isActiveCallback`
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "authentication-core-lib",
+  "version": "0.1.0",
+  "description": "Framework-agnostic authentication core for TypeScript.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "authentication",
+    "jwt",
+    "argon2",
+    "typescript",
+    "library"
+  ],
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    "./login": "./src/login.ts",
+    "./register": "./src/register.ts",
+    "./current-user": "./src/current-user.ts",
+    "./errors": "./src/errors.ts",
+    "./interfaces": "./src/interfaces.ts"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "argon2": "0.44.0",
+    "jsonwebtoken": "9.0.3",
+    "nodemailer": "9.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.0",
+    "typescript": "6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/current-user.ts

@@ -0,0 +1,57 @@
+// @ts-ignore jsonwebtoken is supplied by the server package in generated projects.
+import jwt from "jsonwebtoken";
+
+import {
+    InvalidTokenError,
+    UserInactiveError
+} from "./errors";
+
+export namespace AuthenticationCoreCurrentUser {
+    const DEFAULT_VERIFY_OPTIONS: jwt.VerifyOptions = {
+        algorithms: ["HS256"]
+    };
+
+    function asyncVerify(
+        token: string,
+        secretOrPublicKey: jwt.Secret | jwt.PublicKey,
+        options: jwt.VerifyOptions = {}
+    ): Promise<string | jwt.JwtPayload> {
+        return new Promise((resolve, reject) => {
+            jwt.verify(token, secretOrPublicKey, options, (err: jwt.VerifyErrors | null, decoded: object | string | undefined) => {
+                if (err) reject(err);
+                else resolve(decoded as string | jwt.JwtPayload);
+            });
+        });
+    }
+
+    export async function getCurrentUser(
+        token: string,
+        jwtKey: jwt.Secret,
+        isActiveCallback: (uuid: string) => Promise<boolean>,
+        verifyOptions: jwt.VerifyOptions = {}
+    ): Promise<string> {
+        const options = { ...DEFAULT_VERIFY_OPTIONS, ...verifyOptions };
+
+        let payload: string | jwt.JwtPayload;
+
+        try {
+            payload = await asyncVerify(token, jwtKey, options);
+        } catch (e) {
+            throw new InvalidTokenError("Token verification failed");
+        }
+
+        if (typeof payload === "string") {
+            throw new InvalidTokenError("Invalid token payload type");
+        }
+
+        if (typeof payload.sub !== "string") {
+            throw new InvalidTokenError("Token payload does not contain valid 'sub'");
+        }
+
+        if (!(await isActiveCallback(payload.sub))) {
+            throw new UserInactiveError();
+        }
+
+        return payload.sub;
+    }
+}

package/src/errors.ts

@@ -0,0 +1,41 @@
+export class AuthError extends Error {
+    code: string;
+    statusCode: number;
+
+    constructor(message: string, code: string, statusCode: number) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+        this.statusCode = statusCode;
+    }
+}
+
+export class InvalidCredentialsError extends AuthError {
+    constructor() {
+        super("Invalid credentials", "INVALID_CREDENTIALS", 401);
+    }
+}
+
+export class UserInactiveError extends AuthError {
+    constructor() {
+        super("User is inactive", "USER_INACTIVE", 403);
+    }
+}
+
+export class InvalidTokenError extends AuthError {
+    constructor(message = "Invalid token") {
+        super(message, "INVALID_TOKEN", 401);
+    }
+}
+
+export class MailTakenError extends AuthError {
+    constructor() {
+        super("Email is already taken", "MAIL_TAKEN", 409);
+    }
+}
+
+export class PasswordMismatchError extends AuthError {
+    constructor() {
+        super("Passwords do not match", "PASSWORD_MISMATCH", 400);
+    }
+}

package/src/interfaces.ts

@@ -0,0 +1,28 @@
+export interface FetchedUser {
+    uuid: string;
+    mail: string;
+    password: string;
+    isActive: boolean;
+}
+
+export interface RegistrationInputData {
+    typedMail: string;
+    typedPassword: string;
+    typedPasswordRepeated: string;
+}
+
+export interface VerificationMail {
+    from: string;
+    subject: string;
+    content(uuid: string): string;
+}
+
+export interface MailTransportConfig {
+    host: string;
+    port: number;
+    secure: boolean;
+    auth: {
+        user: string;
+        pass: string;
+    };
+}

package/src/login.ts

@@ -0,0 +1,69 @@
+// @ts-ignore jsonwebtoken is supplied by the server package in generated projects.
+import jwt from "jsonwebtoken";
+// @ts-ignore argon2 is supplied by the server package in generated projects.
+import argon2 from "argon2";
+
+import { FetchedUser } from "./interfaces";
+import {
+    InvalidCredentialsError,
+    UserInactiveError
+} from "./errors";
+
+export namespace AuthenticationCoreLogin {
+    const DEFAULT_JWT_OPTIONS: jwt.SignOptions = {
+        algorithm: "HS256",
+        expiresIn: "7d"
+    };
+
+    function asyncSign(
+        payload: string | object | any,
+        secretOrPrivateKey: jwt.Secret | jwt.PrivateKey,
+        options: jwt.SignOptions = {}
+    ): Promise<string> {
+        return new Promise((resolve, reject) => {
+            jwt.sign(payload, secretOrPrivateKey, options, (err: jwt.VerifyErrors | null, token: string | undefined) => {
+                if (err) reject(err);
+                else resolve(token as string);
+            });
+        });
+    }
+
+    export async function login(
+        typedMail: string,
+        typedPassword: string,
+        fetchedUser: FetchedUser | undefined,
+        jwtKey: jwt.Secret,
+        jwtOptions: jwt.SignOptions = {}
+    ): Promise<string> {
+        // TODO: Refactor validation logic to mitigate timing attacks (Username Enumeration).
+        // Checking 'fetchedUser' and 'typedName' immediately allows attackers to determine
+        // valid usernames based on API response times, as 'argon2.verify' is significantly slower.
+        // Consider running a dummy argon2 verification when a user is not found, or returning
+        // a generic 'InvalidCredentialsError' for all authentication failures.
+        if (!fetchedUser || typedMail !== fetchedUser.mail) {
+            // DUMMY_HASH by dummy generated password
+            const DUMMY_HASH = "$argon2id$v=19$m=16,t=2,p=1$cW5BYVZZc3lqWUplbEgyRA$Bp/WqdeZVSHxIIrTR5EQCw";
+            await argon2.verify(DUMMY_HASH, typedPassword); // Dummy verification to mitigate timing attacks
+            throw new InvalidCredentialsError();
+        }
+
+        if (!(await argon2.verify(fetchedUser.password, typedPassword))) {
+            throw new InvalidCredentialsError();
+        }
+
+        if (!fetchedUser.isActive) {
+            throw new UserInactiveError();
+        }
+
+        const options = { ...DEFAULT_JWT_OPTIONS, ...jwtOptions };
+
+        try {
+            // Signing is async because JWT algorithms may vary in cost.
+            // While HS256 is cheap, other algorithms (e.g. RS256/ES256) or external signers (KMS/HSM)
+            // can be significantly more expensive or I/O-bound, so the API must avoid blocking the event loop.
+            return await asyncSign({ sub: fetchedUser.uuid }, jwtKey, options);
+        } catch (error) {
+            throw new Error("An unexpected error occurred during login.");
+        }
+    }
+}

package/src/register.ts

@@ -0,0 +1,79 @@
+// @ts-ignore argon2 is supplied by the server package in generated projects.
+import argon2 from "argon2";
+// @ts-ignore nodemailer is supplied by the server package in generated projects.
+import nodemailer from "nodemailer";
+
+import { FetchedUser, MailTransportConfig, RegistrationInputData, VerificationMail } from "./interfaces";
+import {
+    AuthError,
+    MailTakenError,
+    PasswordMismatchError
+} from "./errors";
+
+export namespace AuthenticationCoreRegister {
+    const DEFAULT_HASH_OPTIONS: argon2.Options = {
+        type: argon2.argon2id,
+        memoryCost: 2 ** 17,
+        timeCost: 4,
+        parallelism: 1
+    };
+
+    const DEFAULT_MAIL_TRANSPORT_CONFIG: MailTransportConfig = {
+        host: "smtp.example.com",
+        port: 587,
+        secure: false,
+        auth: {
+            user: "max.mustermann@example.com",
+            pass: "password"
+        }
+    };
+
+    export async function register(
+        registrationInputData: RegistrationInputData,
+        mailExistsRoutine: (mail: string) => Promise<boolean>,
+        customInputData: Record<string, unknown>, // e.g. name, address that should be stored in the database for the new user
+        dataProcessing: (identification: string, hashedPassword: string, customInputData: Record<string, unknown>) => Promise<FetchedUser | undefined>,
+        verificationMail: VerificationMail,
+        mailTransportConfig: MailTransportConfig = DEFAULT_MAIL_TRANSPORT_CONFIG,
+        hashOptions: argon2.Options = DEFAULT_HASH_OPTIONS
+    ): Promise<FetchedUser> {
+        let mailExists: boolean;
+
+        try {
+            mailExists = await mailExistsRoutine(registrationInputData.typedMail);
+        } catch (e) {
+            throw e;
+        }
+
+        if (mailExists) {
+            throw new MailTakenError();
+        }
+
+        if (registrationInputData.typedPassword !== registrationInputData.typedPasswordRepeated) {
+            throw new PasswordMismatchError();
+        }
+
+        try {
+            // argon2.hash adds a random salt automatically (embedded in the hash output).
+            const hashedPassword = await argon2.hash(registrationInputData.typedPassword, hashOptions);
+            const newUser = await dataProcessing(registrationInputData.typedMail, hashedPassword, customInputData);
+
+            if (!newUser || !newUser.uuid) {
+                throw new AuthError("Data processing did not return a valid user object with a UUID", "INVALID_USER_OBJECT", 500);
+            }
+
+            const transporter = nodemailer.createTransport(mailTransportConfig);
+
+            await transporter.sendMail({
+                from: verificationMail.from,
+                to: newUser.mail,
+                subject: verificationMail.subject,
+                text: verificationMail.content(newUser.uuid)
+            });
+
+            return newUser;
+        } catch (e) {
+            throw e;
+        }
+    }
+}