@build-from-bits/jwt-authentication

Minimal browser-side JWT auth library with:

• login (username/password) and OTP login (sendOtp → otpLogin)
• access token in sessionStorage
• refresh token in localStorage
• axios auth header injection
• automatic token refresh only on 401 (single in-flight guard + __isRetryRequest)
• startup session bootstrap (verify access, then refresh fallback)
• logout clears both local tokens by default (no server endpoint needed)

Install

npm install @build-from-bits/jwt-authentication

Default Auth Paths

• AUTH_LOGIN_PATH: /v2/auth/token/
• AUTH_REFRESH_PATH: /v2/auth/token/refresh/
• AUTH_VERIFY_PATH: /v2/auth/token/verify/
• AUTH_OTP_SEND_PATH: /v2/auth/otp/send/

AUTH_LOGOUT_PATH is optional and empty by default.

Basic Setup

import { createAuthSystem } from '@build-from-bits/jwt-authentication';

const auth = createAuthSystem({
  baseUrl: 'https://your-api.example.com',
  env: import.meta.env, // Vite apps (also supports process.env / REACT_APP_*)
});

Override Config At Setup Time

const auth = createAuthSystem({
  baseUrl: 'https://api.example.com',
  env: import.meta.env,
  configOverrides: {
    AUTH_LOGIN_PATH: '/custom/auth/login/',
    AUTH_REFRESH_PATH: '/custom/auth/refresh/',
    AUTH_VERIFY_PATH: '/custom/auth/verify/',
    AUTH_OTP_SEND_PATH: '/custom/auth/otp/send/',
    AUTH_HEADER_PREFIX: 'Bearer',
    REFRESH_REQUEST_KEY: 'refresh_token',
    VERIFY_REQUEST_KEY: 'access_token',

    // Optional only if backend supports logout API
    AUTH_LOGOUT_PATH: '/custom/auth/logout/',
    LOGOUT_REQUEST_KEY: 'refresh_token',
    ENABLE_LOGOUT_API_CALL: false,

    // Customize the key for the username/phone field in login request
    LOGIN_USERNAME_KEY: 'username',

    // OTP login field keys
    LOGIN_OTP_CODE_KEY: 'code',
    OTP_PHONE_KEY: 'phone',
  },
  tokenKeys: {
    accessTokenKey: 'my_access_token',
    refreshTokenKey: 'my_refresh_token',
  },
});

Usage

const { authService, client, session } = createAuthSystem({
  baseUrl: 'http://localhost:8000',
  env: import.meta.env,
});

await session.initialize();
await authService.login({ username: 'demo', password: 'demo123' });

const response = await client.get('/v2/user/profile/');
console.log(response.data);

await authService.logout();

OTP Login

// 1. Ask the backend to send the OTP to a phone/email
await authService.sendOtp({ phone: '+911234567890' });

// 2. Exchange { phone, code } for access + refresh tokens
await authService.otpLogin({ phone: '+911234567890', code: '123456' });

Token Storage Policy

• Access token → sessionStorage (wiped when the tab closes).
• Refresh token → localStorage (survives reload so sessions can be bootstrapped).
• Keys are configurable via tokenKeys.

Publish Scripts

npm run pack:check
npm run publish:npm
npm run publish:github

GitHub Actions Release + Publish

Workflow file:

• .github/workflows/release.yml

On push to main, it:

1. runs pre-release checks (npm run lint, npm test, npm run pack:check)
2. reads version from package.json
3. creates tag v<version> if not already present
4. creates a GitHub release
5. publishes package to GitHub Packages (npm.pkg.github.com)

For GitHub Packages, ensure repository/package permissions allow publish.

Browser Demo

A minimal browser demo is included:

• example/index.html
• example/browser-demo.js

Run it with any static server from project root:

npx serve .

Then open:

• http://localhost:3000/example/

Update username, password, and API URL in example/browser-demo.js for your backend.

License

Licensed under the Apache License 2.0.

Copyright 2026 Build From Bits Pvt Ltd.