@kibaofficial/kio-auth-client

Official client SDK for KioAuth - Self-hosted authentication service.

Installation

npm install @kibaofficial/kio-auth-client
# or
pnpm add @kibaofficial/kio-auth-client
# or
yarn add @kibaofficial/kio-auth-client

Quick Start

Core Client (Framework-agnostic)

import { createClient } from '@kibaofficial/kio-auth-client';

const auth = createClient({
  baseUrl: 'https://auth.example.com'
});

// Sign in
try {
  const { user } = await auth.signIn({
    email: '[email protected]',
    password: 'password123'
  });
  console.log('Signed in as:', user.name);
} catch (error) {
  if (error.code === '2FA_REQUIRED') {
    // Show 2FA input
  }
}

// Get current user
const user = await auth.getUser();

// Sign out
await auth.signOut();

React Integration

import { KioAuthProvider, useUser, useAuth } from '@kibaofficial/kio-auth-client/react';

function App() {
  return (
    <KioAuthProvider 
      baseUrl="https://auth.example.com"
      redirectUrl="/dashboard"
    >
      <MyApp />
    </KioAuthProvider>
  );
}

function Profile() {
  const { user, isLoading } = useUser();
  const { signOut } = useAuth();
  
  if (isLoading) return <div>Loading...</div>;
  if (!user) return <div>Not signed in</div>;
  
  return (
    <div>
      <p>Hello {user.name}</p>
      <button onClick={() => signOut()}>Sign Out</button>
    </div>
  );
}

Next.js Integration

// middleware.ts
import { createAuthMiddleware } from '@kibaofficial/kio-auth-client/next';

export default createAuthMiddleware({
  publicRoutes: ['/', '/about', '/auth(.*)'],
  protectedRoutes: ['/dashboard(.*)'],
  authUrl: 'https://auth.example.com',
});

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

API Reference

createClient(config)

Creates a new KioAuth client instance.

const auth = createClient({
  baseUrl: string;          // Required: Your KioAuth server URL
  credentials?: 'include';  // Optional: Cookie handling (default: 'include')
  timeout?: number;         // Optional: Request timeout in ms (default: 30000)
});

Client Methods

Authentication

• signIn({ email, password, totp? }) - Sign in with credentials
• signUp({ email, password, username? }) - Create new account
• signOut() - Sign out current user
• requestPasswordReset(email) - Request password reset email
• resetPassword(token, password) - Reset password with token

User

• getUser() - Get current authenticated user
• updateProfile({ name?, email? }) - Update user profile

Sessions

• getSessions() - Get all active sessions
• revokeSession(sessionId) - Revoke a specific session
• validateSession() - Check if current session is valid

OAuth

• getAccounts() - Get linked OAuth accounts
• unlinkAccount(accountId) - Unlink an OAuth account
• getOAuthLinkUrl(provider) - Get OAuth linking URL

Two-Factor Authentication

• get2FAStatus() - Check if 2FA is enabled
• setup2FA() - Generate 2FA secret and QR code
• verify2FA(code) - Verify and enable 2FA
• disable2FA(code) - Disable 2FA

Login History

• getLoginHistory() - Get login history

Error Handling

import { KioAuthError } from '@kibaofficial/kio-auth-client';

try {
  await auth.signIn({ email, password });
} catch (error) {
  if (error instanceof KioAuthError) {
    switch (error.code) {
      case '2FA_REQUIRED':
        // Show 2FA input
        break;
      case 'INVALID_CREDENTIALS':
        // Show error message
        break;
      case 'RATE_LIMITED':
        // Too many attempts
        break;
      case 'ACCOUNT_BANNED':
        // Account is banned
        break;
    }
  }
}

Requirements

• Node.js 18+
• React 18+ (for React integration)
• Next.js 13+ (for Next.js integration)

License

MIT © KibaOfficial