zksignin-sdk

🔐 Zero-Knowledge Authentication SDK - Plug-and-play authentication system with zero-knowledge proofs

Features

• ✅ Zero-Knowledge Security - Passphrases never leave the client
• ✅ Client-Side Cryptography - PBKDF2 + SHA-256
• ✅ React Support - Ready-to-use components and hooks
• ✅ TypeScript - Full type definitions included
• ✅ Vanilla JS - Works without any framework
• ✅ Session Management - Automatic session persistence
• ✅ Lightweight - Minimal dependencies

Installation

# Using npm
npm install zksignin-sdk

# Using yarn
yarn add zksignin-sdk

Quick Start

Vanilla JavaScript

import { ZKAuth } from 'zksignin-sdk';

const auth = new ZKAuth({
  apiUrl: 'https://backend.yuma.onl/'
});

// Register
const user = await auth.register({
  username: 'alice',
  passphrase: 'my-secure-passphrase',
  name: 'Alice'
});

// Login
const session = await auth.login({
  username: 'alice',
  passphrase: 'my-secure-passphrase'
});

// Check authentication
if (auth.isAuthenticated()) {
  const currentUser = auth.getCurrentUser();
  console.log('Logged in as:', currentUser.username);
}

// Logout
auth.logout();

React

import { AuthProvider, useAuth } from 'zksignin-sdk/react';

// Wrap your app with AuthProvider
function App() {
  return (
    <AuthProvider options={{ apiUrl: 'https://backend.yuma.onl/' }}>
      <YourApp />
    </AuthProvider>
  );
}

// Use the hook in your components
function LoginForm() {
  const { login, isAuthenticated, user } = useAuth();
  const [username, setUsername] = useState('');
  const [passphrase, setPassphrase] = useState('');

  const handleLogin = async () => {
    try {
      await login(username, passphrase);
      console.log('Logged in!');
    } catch (error) {
      console.error('Login failed:', error);
    }
  };

  if (isAuthenticated) {
    return <div>Welcome, {user.username}!</div>;
  }

  return (
    <form onSubmit={(e) => { e.preventDefault(); handleLogin(); }}>
      <input 
        value={username} 
        onChange={(e) => setUsername(e.target.value)} 
        placeholder="Username"
      />
      <input 
        type="password"
        value={passphrase} 
        onChange={(e) => setPassphrase(e.target.value)} 
        placeholder="Passphrase"
      />
      <button type="submit">Login</button>
    </form>
  );
}

API Reference

ZKAuth Class

Constructor

new ZKAuth(options?: AuthOptions)

Options:

• apiUrl (string): API base URL (default: 'https://backend.yuma.onl/')
• iterations (number): PBKDF2 iterations (default: 100000)
• keyLength (number): Key length in bits (default: 256)

Methods

register(data: RegisterData): Promise<AuthSession>

Register a new user with zero-knowledge proof.

const session = await auth.register({
  username: 'alice',
  passphrase: 'secure-passphrase',
  name: 'Alice' // optional
});

login(credentials: LoginCredentials): Promise<AuthSession>

Login with username and passphrase.

const session = await auth.login({
  username: 'alice',
  passphrase: 'secure-passphrase'
});

logout(): void

Logout and clear session.

auth.logout();

isAuthenticated(): boolean

Check if user is authenticated.

if (auth.isAuthenticated()) {
  // User is logged in
}

getCurrentUser(): User | null

Get current authenticated user.

const user = auth.getCurrentUser();
console.log(user.username);

validatePassphrase(passphrase: string): PassphraseValidation

Validate passphrase strength.

const validation = auth.validatePassphrase('my-passphrase');
console.log(validation.strength); // 'weak' | 'medium' | 'strong'

React Hooks

useAuth()

Access authentication context in React components.

const {
  user,              // Current user or null
  isAuthenticated,   // Boolean auth status
  isLoading,         // Loading state
  login,             // Login function
  register,          // Register function
  logout,            // Logout function
  updateProfile,     // Update profile function
  getCurrentUser,    // Get current user function
  refreshSession     // Refresh session function
} = useAuth();

React Components

<AuthProvider>

Provides authentication context to your app.

<AuthProvider options={{ apiUrl: 'https://backend.yuma.onl/' }}>
  <App />
</AuthProvider>

Props:

• options (AuthOptions): Authentication configuration
• children (ReactNode): Child components

TypeScript Support

Full TypeScript definitions are included:

import { 
  ZKAuth, 
  User, 
  AuthSession, 
  RegisterData,
  LoginCredentials 
} from 'zksignin-sdk';

const auth = new ZKAuth({
  apiUrl: 'https://backend.yuma.onl/'
});

// All types are automatically inferred
const session: AuthSession = await auth.login({
  username: 'alice',
  passphrase: 'secure-passphrase'
});

Security

Zero-Knowledge Architecture

1. Client-Side Only: All cryptographic operations happen in the browser
2. No Password Storage: Server only stores cryptographic commitments
3. PBKDF2 Key Derivation: 100,000 iterations with SHA-256
4. Unique Salts: Each user has a unique salt for key derivation
5. Timestamp-Based Commitments: Prevents replay attacks

Authentication Flow

Registration:
1. User enters passphrase
2. Generate random salt
3. Derive key using PBKDF2
4. Create commitment (hash of key + timestamp)
5. Create proof (hash of key + commitment + username)
6. Send commitment, salt, proof, timestamp to server
7. Server stores commitment and salt

Login:
1. User enters passphrase
2. Fetch salt and timestamp from server
3. Derive key using stored salt
4. Recreate commitment with stored timestamp
5. Verify commitment matches
6. Create proof
7. Send proof to server for verification
8. Server verifies and returns session token

Examples

Validate Before Registration

const auth = new ZKAuth();

// Validate passphrase strength
const validation = auth.validatePassphrase(passphrase);

if (!validation.valid) {
  alert(validation.message);
  return;
}

if (validation.strength === 'weak') {
  alert('Please use a stronger passphrase');
  return;
}

// Proceed with registration
await auth.register({ username, passphrase });

Custom API URL

const auth = new ZKAuth({
  apiUrl: 'https://api.myapp.com'
});

Handle Errors

try {
  await auth.login({ username, passphrase });
} catch (error) {
  if (error.message === 'User not found') {
    // Handle user not found
  } else if (error.message === 'Invalid passphrase') {
    // Handle wrong passphrase
  } else {
    // Handle other errors
  }
}

React: Protected Route

import { useAuth } from 'zksignin-sdk/react';

function ProtectedPage() {
  const { isAuthenticated, isLoading, user } = useAuth();

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (!isAuthenticated) {
    return <div>Please login to access this page</div>;
  }

  return <div>Welcome, {user.username}!</div>;
}

Building from Source

# Install dependencies
yarn install

# Build the package
yarn build

# The build outputs to /dist folder

License

MIT © YUMA Team

Support

• Documentation: https://yuma.onl/app/zksignin
• Issues: https://github.com/useyuma
• Email: [email protected]

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Made with ❤️ by the YUMA Team