npm package: @promedev/auth-core
Description: Reusable authentication core library by Promedev
Author: promedev
Latest version: 1.0.0

# 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):

```bash
npm install auth-core
```

Local development (from this repo):

```bash
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.

```ts
// 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("user@example.com", "password");
const tokens = await auth.signIn("user@example.com", "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.

```ts
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

```ts
const user = await auth.signUp("user@example.com", "password");
const tokens = await auth.signIn("user@example.com", "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):

```yaml
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.