auth-core

Lightweight authentication core (JWT + refresh tokens + OAuth provider interfaces).

This package is designed as a small, testable authentication module for learning and small projects. It exposes AuthCore, domain types, and a few in-memory infra implementations.

Quick start

Install (if published):

npm install auth-core

Local development (from this repo):

npm ci
npm run build
npm test

Usage

Important: the library does not load environment files itself. Your application is responsible for providing environment variables (e.g. JWT_SECRET) or injecting dependencies. This avoids side-effects when importing the library.

Factory (recommended)

The easiest way to get started is with the createAuthCore factory. It sets up AuthCore with in-memory storage and reads environment variables for JWT configuration.

// 1. Load environment variables (e.g. from .env file)
import "dotenv/config";

// 2. Create the AuthCore instance
import { createAuthCore } from "auth-core";

const auth = createAuthCore();

// 3. Use it
const user = await auth.signUp("[email protected]", "password");
const tokens = await auth.signIn("[email protected]", "password");
console.log(tokens.accessToken);

The factory requires JWT_SECRET to be set in your environment. You can also set JWT_ACCESS_TOKEN_EXPIRES_IN and JWT_REFRESH_TOKEN_EXPIRES_IN.

Dependency Injection (advanced)

For more control or to use your own infrastructure (e.g. a database user repository), you can inject dependencies into the services and then create an AuthCore instance manually.

import { AuthCore } from "auth-core";
import { AuthService, UserService } from "auth-core/core";
import { JwtService } from "auth-core/domain";
import { MemoryUserRepo, MemoryTokenStore } from "auth-core/infra";
import { PasswordService } from "auth-core/domain";

// 1. Create infrastructure components
const userRepo = new MemoryUserRepo();
const tokenStore = new MemoryTokenStore();

// 2. Create domain services
const passwordService = new PasswordService();
const jwtService = new JwtService({
  jwtSecret: process.env.JWT_SECRET!,
  accessTokenExpiresIn: "1h",
  refreshTokenExpiresIn: "7d",
});

// 3. Create core services
const userService = new UserService(userRepo, passwordService);
const authService = new AuthService(
  userRepo,
  tokenStore,
  passwordService,
  jwtService
);

// 4. Create the AuthCore instance
const auth = new AuthCore(userService, authService);

Quick example: sign up / sign in

const user = await auth.signUp("[email protected]", "password");
const tokens = await auth.signIn("[email protected]", "password");
console.log(tokens.accessToken, tokens.refreshToken);

Testing and CI

Tests rely on JWT_SECRET being set. For local development we provide a Jest setup that injects a test secret. In CI, set JWT_SECRET as an environment variable or secret.

CI example (GitHub Actions):

env:
  JWT_SECRET: ${{ secrets.JWT_SECRET }}
steps:
  - uses: actions/checkout@v3
  - run: npm ci
  - run: npm test

Security notes

• Do not commit secrets into source control.
• For production, use a secure secret manager and avoid storing refresh tokens in plaintext.
• Consider hashing refresh tokens before persisting (e.g. store sha256(token) instead of the token itself).

Publishing notes

• The library does not load environment variables by itself. Load .env at your application entry point or use a secrets manager to inject required values.
• package.json files is configured to include only the dist artifact in the published package. Test and config files are not included in the published package.
• Minimum Node version is >=18 (see project package.json).

Node / Environment

This package requires Node >= 18 (uses crypto.randomUUID() and relies on Node runtime capabilities). If you need wider support, consider polyfills or shims.

Contributing

PRs are welcome. Keep tests green and follow semantic versioning for releases.