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

``bash


Using npm

`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();
`

$3

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

// Wrap your app with AuthProvider
function App() {
return (



);
}

// 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

`typescript
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

Register a new user with zero-knowledge proof.

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

##### login(credentials: LoginCredentials): Promise

Login with username and passphrase.

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

##### logout(): void

Logout and clear session.

`javascript
auth.logout();
`

##### isAuthenticated(): boolean

Check if user is authenticated.

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

##### getCurrentUser(): User | null

Get current authenticated user.

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

##### validatePassphrase(passphrase: string): PassphraseValidation

Validate passphrase strength.

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

$3

#### useAuth()

Access authentication context in React components.

`typescript
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();
`

$3

####

Provides authentication context to your app.

`jsx



`

Props:
- options (AuthOptions): Authentication configuration
- children (ReactNode): Child components

TypeScript Support

Full TypeScript definitions are included:

`typescript
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

$3

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

$3

`
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

$3

`javascript
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 });
`

$3

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

$3

`javascript
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
}
}
`

$3

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

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

if (isLoading) {
return

`bash


Install dependencies

License

MIT © YUMA Team

Support

- Documentation: https://yuma.onl/app/zksignin
- Issues: https://github.com/useyuma
- Email: hi@yuma.onl

Contributing

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

---

Made with ❤️ by the YUMA Team