A Unified, Framework-Agnostic Frontend Authentication Suite
Supporting Multi-Provider OAuth (Google, Apple, Meta, Line, Kakao, Naver), Developer (GitHub, Discord), Web3 (SIWE), Identity (World ID Orb, Passkey WebAuthn), Reactive Store, Axios/Fetch Interceptors, and RBAC/ABAC Guards.
🎮 Try the Live Interactive Demo: https://yoonjonglyu.github.io/isa-auth/
Experience 11 authentication providers, real-time reactive store visualization, dynamic button layouts, and wildcard RBAC guard checks directly in your browser without any setup!
Modern web applications frequently require diverse authentication methods — from global platforms (Google, Apple, Meta) and local portals (Kakao, Naver, Line) to developer communities (GitHub, Discord), decentralized Web3 wallets (SIWE), and next-generation biometric/identity systems (World ID Orb & Passkey).
ISA AUTH provides an all-in-one, frontend-centric architecture that is:
- Framework-Agnostic: Works seamlessly across Vanilla JS, React, Vue, Svelte, or Web Components.
- Zero Node.js Dependencies: Pure browser-safe cryptographic & JWT utilities with zero Node runtime bloat.
- Categorized Provider Taxonomy: Organized into
social,developer,web3, andidentitydomains. - Next-Gen Identity & Biometrics: Native support for World ID (Orb Proof-of-Personhood) and Passkey (FIDO2 WebAuthn).
- Enterprise-Ready RBAC/ABAC: Wildcard permission matching (
users:*), role hierarchy inheritance, and router navigation guards. - HTTP Interceptors (Axios & Fetch): Auto
Authorization: Bearer <token>injection and deduplicated 401 refresh queues. - Token Exchange Standard: Standardized adapter for exchanging OAuth codes, World ID proofs, and Passkey assertions with backend APIs.
- Flexible Storage Modes: Multi-tab synchronization, prefix isolation, and HttpOnly Cookie / Hybrid BFF mode.
npm install isa-auth
# or
yarn add isa-auth
# or
pnpm add isa-auth[UI Layer] Vanilla DOM / React / Vue / Web Component (<isa-auth-button>)
│
[Unified Facade] IsaAuth (packages/isa-auth)
│
┌──────────────┼──────────────┬──────────────┐
▼ ▼ ▼ ▼
[Providers] [Service] [Store] [Guards & HTTP]
├─ Social - JwtService - Memory - createAuthGuard (RBAC/ABAC)
│ (Google, Apple,- BaseService - Local - Wildcard & Hierarchy
│ Meta/FB, - TokenExchange - Session - Navigation Guard
│ Kakao, Naver,- AutoRefresh - Cookie - onUnauthorized Hook
│ LINE) - PKCE Utils - Tab Sync - createAuthFetch (Auto 401)
├─ Developer - applyAuthInterceptor (Axios)
│ (GitHub, Discord)
├─ Web3
│ (Ethereum SIWE)
└─ Identity
(World ID Orb, Passkey FIDO2)
| Category | Providers | Key Features |
|---|---|---|
social |
Google, Apple, Meta/Facebook, Kakao, Naver, LINE | Native SDK wrappers, OpenID Connect, OAuth 2.0 PKCE |
developer |
GitHub, Discord | Developer OAuth 2.0 PKCE, Bot/Server authorization |
web3 |
Ethereum SIWE (EIP-4361) | EIP-1193 wallet detection, personal_sign signature |
identity |
World ID (Orb), Passkey (WebAuthn/FIDO2) | ZK-SNARK Proof of Personhood, Face ID / Touch ID / Windows Hello |
💡 Developer Keys Setup: Need help obtaining Client IDs, API Keys or configuring Redirect URIs? Check out our complete Provider Environment Setup Guide.
Manage multiple social logins, developer platforms, and Web3/Passkey authentication simultaneously in a single application instance:
import { IsaAuth } from 'isa-auth';
// 1. Initialize with multiple providers at once
const auth = new IsaAuth({
storage: 'memory', // Production security default
providers: {
google: { clientId: 'GOOGLE_CLIENT_ID', callbackUrl: 'https://myapp.com/callback' },
kakao: { clientId: 'KAKAO_JAVASCRIPT_KEY', callbackUrl: 'https://myapp.com/callback' },
apple: { clientId: 'com.myapp.service', callbackUrl: 'https://myapp.com/callback' },
github: { clientId: 'GITHUB_CLIENT_ID', callbackUrl: 'https://myapp.com/callback' },
passkey: { rpName: 'My App', rpId: 'myapp.com' },
},
});
// 2-A. Trigger a specific provider login programmatically
await auth.signIn('kakao');
// or
await auth.signIn('google');
// 2-B. Render individual provider button
auth.renderButton('github', document.getElementById('github-btn-slot'));
// 2-C. Render all buttons at once with customizable layout (grid / column / row)
auth.renderAllButtons(document.getElementById('social-login-container'), {
direction: 'grid', // 'grid' | 'column' | 'row'
gap: '12px',
});
// 3. Inspect registered providers
console.log(auth.getRegisteredProviders()); // ['google', 'kakao', 'apple', 'github', 'passkey']import { IsaAuth } from 'isa-auth';
// Initialize with a single provider
const auth = new IsaAuth({
provider: 'google', // 'google' | 'apple' | 'meta' | 'github' | 'discord' | 'web3' | 'world' | 'passkey'
clientId: 'YOUR_CLIENT_ID',
callbackUrl: 'https://myapp.com/auth/callback',
storage: 'memory',
storagePrefix: 'myapp',
});
// Render button to a DOM container
auth.renderButton(document.getElementById('login-container'));
// Listen to authentication changes
auth.subscribe((isAuthenticated) => {
if (isAuthenticated) {
console.log('User Profile:', auth.getUserInfo());
console.log('Access Token:', auth.getAccessToken());
}
});Verify unique humanness using World ID Orb Proof-of-Personhood:
import { IsaAuth } from 'isa-auth';
const worldAuth = new IsaAuth({
provider: 'world',
clientId: 'app_staging_your_app_id',
extraOptions: {
action: 'vote',
verificationLevel: 'orb', // 'orb' (Biometric iris scan) or 'device'
signal: 'user_wallet_address',
onSuccess: (proof) => {
console.log('Proof nullifier:', proof.nullifier_hash);
console.log('ZK-SNARK proof:', proof.proof);
},
},
});
await worldAuth.signIn();
const user = await worldAuth.getUserInfo();
console.log(user.isHuman); // trueSeamless passwordless authentication via Face ID, Touch ID, or Windows Hello:
import { IsaAuth } from 'isa-auth';
const passkeyAuth = new IsaAuth({
provider: 'passkey',
extraOptions: {
rpName: 'My Enterprise Bank',
userName: 'alice@example.com',
},
});
// Authenticate with device biometrics
await passkeyAuth.signIn();
// Register a new passkey credential
await passkeyAuth.providerInstance.registerCredential();Automatically attaches Authorization: Bearer <token> and queues concurrent requests while refreshing expired tokens:
import axios from 'axios';
import { IsaAuth } from 'isa-auth';
const auth = new IsaAuth({ provider: 'jwt' });
const apiClient = axios.create({ baseURL: 'https://api.example.com' });
// Applies request/response interceptors to Axios
auth.applyAxiosInterceptor(apiClient, {
refreshFn: async () => {
const res = await axios.post('/api/auth/refresh');
return res.data.accessToken;
},
onUnauthorized: () => {
window.location.href = '/login';
},
});
// All requests now have automatic Bearer token injection and 401 recovery
const response = await apiClient.get('/users/me');const authFetch = auth.createFetch({
baseUrl: 'https://api.example.com',
refreshFn: async () => {
const res = await fetch('/api/auth/refresh', { method: 'POST' });
const data = await res.json();
return data.accessToken;
},
});
const res = await authFetch('/protected/data');Supports wildcard permission rules (users:*, *:read, *) and hierarchical role inheritance:
import { IsaAuth } from 'isa-auth';
const auth = new IsaAuth({ provider: 'jwt' });
// Instant wildcard check
auth.can('users:read'); // true if user has 'users:*' or '*'
auth.is('ADMIN'); // role check
// Navigation Guard for React Router / Vue Router
const navGuard = auth.createNavigationGuard({
requireAuth: true,
roles: ['ADMIN'],
roleHierarchy: {
SUPERUSER: ['ADMIN', 'MANAGER'],
ADMIN: ['USER'],
},
permissions: ['reports:read'],
redirectToOnUnauthenticated: '/login',
redirectToOnUnauthorized: '/forbidden',
onRedirect: (path) => router.push(path),
});
// Use inside router beforeEach hook
const result = await navGuard();
if (!result.allowed) {
console.warn('Denied reason:', result.reason);
}Standardized bridge for exchanging OAuth authorization codes, World ID proofs, and Passkey assertions with your backend API:
import { IsaAuth } from 'isa-auth';
const auth = new IsaAuth({ provider: 'github' });
const exchange = auth.createTokenExchange('/api/auth/token-exchange');
// 1. Exchange OAuth code for backend JWT
const tokenRes = await exchange.exchangeOAuthCode('github', 'oauth_code_123');
auth.setAccessToken(tokenRes.accessToken);
// 2. Exchange World ID ZK-Proof for backend session
const worldRes = await exchange.exchangeWorldProof(worldProof);
auth.setAccessToken(worldRes.accessToken);By default, isa-auth uses 'memory' storage to ensure sensitive tokens are never exposed to XSS attacks via browser localStorage:
// 1. [PRODUCTION DEFAULT] Zero XSS In-Memory Storage
const secureAuth = new IsaAuth({
provider: 'jwt',
storage: 'memory', // Default! (No tokens in localStorage)
});
// 2. [PRODUCTION RECOMMENDED] HttpOnly Cookie / BFF Mode
const cookieAuth = new IsaAuth({
provider: 'base',
storage: 'cookie', // CookieSessionStorageAdapter (BFF architecture)
});
// 3. [LOCAL DEV ONLY] Insecure LocalStorage for F5 Refresh Convenience
const devAuth = new IsaAuth({
provider: 'google',
clientId: 'dev-client-id',
storage: 'dev_insecure_localStorage', // Explicitly warns in console that this is NOT for production!
});Backend token exchange & verification engine designed to receive frontend OAuth codes, Web3 SIWE signatures, Passkey assertions, and World ID proofs, validating them and issuing secure app JWTs.
npm install isa-auth-serverimport { IsaAuthServer, createExpressHandler, createNextRouteHandler } from 'isa-auth-server';
const authServer = new IsaAuthServer({
jwt: {
secret: process.env.JWT_SECRET!,
expiresInSeconds: 3600,
},
providers: {
google: { clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret: process.env.GOOGLE_CLIENT_SECRET! },
kakao: { clientId: process.env.KAKAO_CLIENT_ID!, clientSecret: process.env.KAKAO_CLIENT_SECRET! },
},
worldId: { appId: process.env.WORLD_ID_APP_ID! },
});
// Express.js
app.post('/api/auth/exchange', createExpressHandler(authServer));
// Next.js App Router (app/api/auth/exchange/route.ts)
export const POST = createNextRouteHandler(authServer);Official Model Context Protocol (MCP) server enabling AI coding assistants (Claude Desktop, Cursor, Antigravity) to evaluate permissions, inspect JWTs, and verify signatures via Stdio.
// Add to claude_desktop_config.json:
{
"mcpServers": {
"isa-auth": {
"command": "npx",
"args": ["-y", "isa-auth-mcp"]
}
}
}isa_check_permission: Evaluates wildcard RBAC (users:*) and role inheritance hierarchies.isa_inspect_jwt: Parses JWT tokens, extracts claims, and calculates remaining TTL seconds.isa_verify_siwe: Validates EIP-4361 Sign-In with Ethereum format and address matching.isa_scaffold_provider: Generates provider setup code and.envtemplate for any of the 11 providers.
Run the local playground or execute the complete test framework:
# 1. Build entire monorepo
yarn build
# 2. Run test framework (33 unit & integration tests)
yarn test
# 3. Launch interactive playground
yarn demo
# Open http://localhost:3000 in your browserThis project is licensed under the MIT License.