Aizvi/Auth

Reusable, framework-agnostic auth layer for Node.js backends: signup, email verification, login, password reset, and JWT sessions for both web (httpOnly cookie) and mobile (access token plus rotating refresh token) clients.

The frontend never talks to these packages directly. React, Vue, Angular, Next.js, or a mobile app all just call the HTTP endpoints this package mounts (/auth/login, /auth/signup, etc.) with plain fetch.

Packages

Package	Publishes as	What it does
packages/core	@aizvi/auth	All auth logic plus an Express router factory. Has no database of its own; it takes an AuthAdapter.
packages/sqlite	@aizvi/auth-sqlite	A SQLite (better-sqlite3) implementation of AuthAdapter.
packages/postgres	@aizvi/auth-postgres	A PostgreSQL (pg) implementation of AuthAdapter.

Other databases (MySQL, MongoDB, etc.) are supported by writing a small adapter against the same AuthAdapter interface. See packages/core/src/types.ts.

Install

Published to the public npm registry, so any package manager works the same way:

npm install @aizvi/auth @aizvi/auth-sqlite express
pnpm add @aizvi/auth @aizvi/auth-sqlite express
yarn add @aizvi/auth @aizvi/auth-sqlite express
bun add @aizvi/auth @aizvi/auth-sqlite express

Or, using Postgres instead of SQLite:

npm install @aizvi/auth @aizvi/auth-postgres express
pnpm add @aizvi/auth @aizvi/auth-postgres express
yarn add @aizvi/auth @aizvi/auth-postgres express
bun add @aizvi/auth @aizvi/auth-postgres express

Usage

import express from 'express';
import { createAuthRouter } from '@aizvi/auth';
import { sqliteAdapter } from '@aizvi/auth-sqlite';

const app = express();
app.use(express.json());

app.use(
  '/auth',
  createAuthRouter({
    adapter: sqliteAdapter({ file: './data.sqlite' }),
    mailer: myEmailSender, // implement EmailSender against your own mail provider
    jwtSecret: process.env.JWT_SECRET!,
  })
);

app.listen(3000);

Or, using @aizvi/auth-postgres instead:

import { postgresAdapter } from '@aizvi/auth-postgres';

app.use(
  '/auth',
  createAuthRouter({
    adapter: await postgresAdapter({ connectionString: process.env.DATABASE_URL! }),
    mailer: myEmailSender,
    jwtSecret: process.env.JWT_SECRET!,
  })
);

API routes

All routes are mounted under whatever path the router is attached to (/auth in the example above).

Method	Path	Description
POST	/signup	Creates an account and sends a verification code by email.
POST	/verify-email	Confirms a verification code and marks the account verified.
POST	/resend-verification	Sends a new verification code, subject to a cooldown.
POST	/login	Signs in with email and password.
POST	/refresh	Rotates a mobile refresh token and issues a new access and refresh token pair.
POST	/forgot-password	Sends a password reset code by email.
POST	/reset-password	Resets the password using a reset code.
GET	/me	Returns the currently authenticated user. Requires authentication.
POST	/logout	Signs out and revokes the refresh token if one is provided.

Web clients (no special header) receive an httpOnly session cookie. Clients sending X-Client-Type: mobile receive { accessToken, refreshToken } in the JSON response body instead.

Development

This repo is built and tested with Bun.

bun install
bun run build
bun test
bun run typecheck
bun run lint

test and typecheck each build packages/core first automatically, since packages/sqlite and packages/postgres both resolve @aizvi/auth through its built output.

Releasing

Releases are automated via the Changesets GitHub Action:

1. On your PR, run bun run changeset to describe the change and choose a version bump. Commit the generated .changeset/*.md file alongside your code changes.
2. Once the PR is merged to main, the release workflow opens (or updates) a "Version Packages" pull request that applies the version bump(s) and updates each package's changelog.
3. Merging that PR triggers the workflow to build all packages and publish them to npm automatically. No manual npm publish step required.

To do any of this manually instead (e.g. for a one-off local release):

bun run changeset   # describe the change, choose a version bump
bun run version     # apply version bumps + update changelogs
bun run release     # build all packages and publish to npm

Commits follow Conventional Commits (feat:, fix:, chore:, test:, docs:, refactor:).

Code of Conduct

See CODE_OF_CONDUCT.md.

License

MIT (see license.txt)