Pico Auth

0.0.43 verified Sat Apr 25 auth: no javascript

A minimal authentication library (v0.0.43, alpha) providing user/password login, TOTP-based MFA, and impersonation support. Focuses on simplicity and flexibility by letting callers supply custom UserProvider and ImpersonateProvider interfaces. Ships TypeScript types and offers JWT token issuance with refresh tokens. Active development with frequent updates.

Common errors

error Error: getUser must return a BaseUser object ↓

cause UserProvider.getUser returned null or undefined instead of a valid user object.

fix

Ensure getUser returns a Promise<BaseUser>; if user not found, throw an error instead of returning null.

error TypeError: Cannot destructure property 'token' of undefined ↓

cause authenticate() returned undefined due to missing userProvider or jwtSpecs fields.

fix

Check that all required arguments are provided: login, password, userProvider, and jwtSpecs.

error Cannot read properties of undefined (reading 'secretKey') ↓

cause jwtSpecs object is missing secretKey property.

fix

Ensure jwtSpecs has both secretKey and expiryTimeMs defined.

Warnings

gotcha UserProvider.getUser must return a BaseUser typed object with a 'blocked' field optional; otherwise, blocked users are still authenticated if not checked manually. ↓

fix Implement getUser to return a user with 'blocked' set to true for blocked users, or use custom logic.

gotcha The 'impersonateEntity' parameter in authenticate is typed as any; passing an invalid entity can crash without clear error. ↓

fix Ensure impersonateEntity matches your ImpersonateProvider's expectations.

gotcha JWTSpecs.expiryTimeMs accepts any type; passing a string instead of number may cause runtime errors. ↓

fix Always pass a number for expiryTimeMs.

Install

npm install pico-auth

yarn add pico-auth

pnpm add pico-auth

Imports

authenticate

wrong

const authenticate = require('pico-auth').authenticate

correct

import { authenticate } from 'pico-auth'

ESM-only; no default export.

refreshToken
```
import { refreshToken } from 'pico-auth'
```
Named export for refreshing JWT tokens.

UserProvider

wrong

import { userProvider } from 'pico-auth'

correct

import { UserProvider } from 'pico-auth'

TypeScript type export; case-sensitive.

mfaRegister

wrong

import { mfa_register } from 'pico-auth'

correct

import { mfaRegister } from 'pico-auth'

camelCase export name.

Quickstart

Demonstrates basic password authentication with custom UserProvider and JWT spec, outputting access and refresh tokens.

import { authenticate } from 'pico-auth';

const userProvider = {
  async getUser(login: string) {
    // mock: return user from DB
    return { id: 'user1', passwordHash: 'hashed_pw', name: 'Test User' };
  },
  async putUser(user: any) { return user; },
  userPasswordPath: 'passwordHash',
};

const jwtSpecs = {
  secretKey: process.env.JWT_SECRET || 'changeme',
  expiryTimeMs: 3600000, // 1 hour
};

async function main() {
  const tokens = await authenticate('user1', 'password123', undefined, undefined, userProvider, undefined, jwtSpecs);
  console.log('Access token:', tokens.token);
  console.log('Refresh token:', tokens.refreshToken);
}

main().catch(console.error);