auth-mini

library0.2.0jsnpmunverified

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.

auth-security web-framework database

npm install auth-mini

github ↗package ↗

INSTALL

IMPORT

SIG · AUTH-MINI

auth-mini

auth-securityjavascriptv0.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AuthMini

✓ import { AuthMini } from 'auth-mini'

✗ const { AuthMini } = require('auth-mini')

ESM-only package; CommonJS require not supported. Use dynamic import if needed.

authMin

✓ import authMin from 'auth-mini'

✗ const authMin = require('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.

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'); });

auth-mini --version

Debug

Known issues

breakingRequires Node.js >=20.10.0; older versions will throw syntax errors.

fix

Upgrade Node.js to v20.10.0 or later.

affects: <20.10.0

breakingESM-only package; CommonJS require() will not work.

fix

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

affects: >=0.1.0

deprecatedDefault export will be removed in v1.0.0 in favor of named exports.

fix

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

affects: >=0.1.0 <1.0.0

gotchaDatabase 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.

affects: >=0.1.0

gotchaJWT secret must be at least 32 characters long; shorter secrets cause runtime error.

fix

Provide a JWT secret of at least 32 characters.

affects: >=0.1.0

breakingSession secret and JWT secret must be different; using same value will throw.

fix

Provide two distinct secrets for session and JWT.

affects: >=0.1.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module

CommonJS require() used with ESM-only package.

fix

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

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

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

fix

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

Error: secret must be at least 32 characters long

JWT or session secret is too short.

fix

Provide a secret string of 32 or more characters.

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

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

fix

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

Error: CORS origin must be a string or array

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

fix

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

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

noderequiredRequires Node >=20.10.0 for built-in features

Agent activity

39 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/zccz14/auth-mini ↗

packagehttps://www.npmjs.com/package/auth-mini ↗