Auth Mini

0.2.0 verified Sat Apr 25 auth: no javascript

Minimal, opinionated authentication server (v0.2.0) for apps needing a solid auth core without external dependencies. Supports password-less sign-in via email OTP, WebAuthn passkeys, and Ed25519 keys. Uses SQLite for storage, issues JWT access tokens with opaque refresh tokens, and provides JWKS endpoints for key rotation. Released infrequently as a pre-1.0 project. Differentiates from Auth0/Firebase by being self-hosted with no external database servers required.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module ↓

cause CommonJS require() used with ESM-only package.

fix

Use import statement or dynamic import() instead of require().

error TypeError: Cannot read properties of undefined (reading 'start') ↓

cause Trying to call .start() on the default export object without wrapping.

fix

Ensure you imported correctly: const server = authMin(options); await server.start();

error Error: secret must be at least 32 characters long ↓

cause JWT or session secret is too short.

fix

Provide a secret string of 32 or more characters.

error Error: open ./auth.db: unable to open database file ↓

cause Database path missing 'file:' prefix or directory not writable.

fix

Set database to 'file:./auth.db' (with file: prefix) and ensure directory exists.

error Error: CORS origin must be a string or array ↓

cause CORS origin provided as non-string value (e.g., undefined or object).

fix

Set cors.origin to a string URL or array of strings.

Warnings

breaking Requires Node.js >=20.10.0; older versions will throw syntax errors. ↓

fix Upgrade Node.js to v20.10.0 or later.

breaking ESM-only package; CommonJS require() will not work. ↓

fix Use import syntax or dynamic import() in CommonJS files.

deprecated Default export will be removed in v1.0.0 in favor of named exports. ↓

fix Use import { AuthMini } from 'auth-mini'; instead of default import.

gotcha Database path must use file: prefix for SQLite; relative paths without file: will fail. ↓

fix Set database to 'file:./auth.db' or similar absolute 'file:' URI.

gotcha JWT secret must be at least 32 characters long; shorter secrets cause runtime error. ↓

fix Provide a JWT secret of at least 32 characters.

breaking Session secret and JWT secret must be different; using same value will throw. ↓

fix Provide two distinct secrets for session and JWT.

Install

npm install auth-mini

yarn add auth-mini

pnpm add auth-mini

Imports

AuthMini
wrong
```
const { AuthMini } = require('auth-mini')
```
correct
```
import { AuthMini } from 'auth-mini'
```
ESM-only package; CommonJS require not supported. Use dynamic import if needed.
authMin
wrong
```
const authMin = require('auth-mini')
```
correct
```
import authMin from 'auth-mini'
```
Default export for quick setup. Requires ESM environment.
Authenticator
```
import { Authenticator } from 'auth-mini'
```
TypeScript type for authenticator instances. If using JS, omit.

Quickstart

Shows how to create and start an Auth Mini server with email transport, CORS configuration, and required secrets.

import authMin from 'auth-mini';

const server = authMin({
  port: 3000,
  database: 'file:./auth.db',
  secrets: {
    jwtSecret: process.env.JWT_SECRET ?? 'change-me',
    sessionSecret: process.env.SESSION_SECRET ?? 'change-me'
  },
  email: {
    from: 'noreply@example.com',
    transport: {
      host: 'smtp.example.com',
      port: 587,
      auth: {
        user: process.env.SMTP_USER ?? '',
        pass: process.env.SMTP_PASS ?? ''
      }
    }
  },
  cors: {
    origin: 'https://myapp.com'
  }
});

server.start().then(() => {
  console.log('Auth Mini running on port 3000');
});