@novyse/auth

A standalone authentication client SDK for the Novyse ecosystem. This library abstracts the complex cryptographic challenges required by the OPAQUE protocol (zero-knowledge password proof), making authentication plug-and-play for client applications (React Native, Electron, Web). It also handles API requests for session management, API keys, QR code authentication, and user account lifecycle.

Installation

npm

npm install @novyse/auth

yarn

yarn add @novyse/auth

bun

bun add @novyse/auth

pnpm

pnpm add @novyse/auth

Initialization

Initialize the library by passing the target environment and a storage adapter for token persistence.

import { NovyseAuth } from "@novyse/auth";
import * as SecureStore from "expo-secure-store";

export const auth = new NovyseAuth({
  branch: "production", // "development" | "preview" | "production"
  platform: "mobile", // "mobile" | "desktop" | "web"
  storageAdapter: {
    getItem: (key) => SecureStore.getItemAsync(key),
    setItem: (key, val) => SecureStore.setItemAsync(key, val),
    removeItem: (key) => SecureStore.deleteItemAsync(key),
  },
});

Available Methods

The NovyseAuth instance exposes the following modular methods:

Authentication (OPAQUE)

• auth.signup.opaque(username, password, name, gdpr, turnstileToken): Register a new user securely without sending the plaintext password.
• auth.signin.opaque(username, password, turnstileToken): Authenticate a user and negotiate session keys.
• auth.logout(): Terminate the current session on the backend.

Security Settings

• auth.settings.opaque(newPassword): Change the user's password using OPAQUE registration.
• auth.account.delete(): Permanently delete the user's account.

Session Management

• auth.settings.session.getCurrent(): Retrieve details about the current active session.
• auth.settings.session.list(): List all active sessions across devices.
• auth.settings.session.revoke(sessionId): Revoke a specific session.
• auth.settings.session.revokeOther(): Revoke all sessions except the current one.

API Keys

• auth.apikey.list(): Retrieve all API keys generated by the user.
• auth.apikey.create(name, permissions, expiresIn): Generate a new API key.
• auth.apikey.toggleActive(id, active): Enable or disable a specific API key.
• auth.apikey.revoke(id): Permanently delete an API key.

QR Code Login

• auth.qrcode.new(): Generate a new QR code session for another device to scan.
• auth.qrcode.status(token): Poll the status of a pending QR code login attempt.
• auth.qrcode.authenticate(token): Authorize a QR code session from an already authenticated device.

Token Management

The SDK manages the JWT automatically for you, including refreshing it before it expires. If you need to access the token directly or listen for invalid session events, you can use the auth.token methods:

• auth.token.get(): Returns a promise that resolves to the valid JWT string, or null if the user is not authenticated. It automatically handles token refreshes under the hood.
• auth.token.onUpdate(callback): Listen for updates to the JWT (e.g. upon successful login or token refresh). Useful for syncing other services like Firebase FCM or WebSocket connections.
• auth.token.onInvalidSession(callback): Register a hook that will be called if the session is revoked or completely expires. This is the perfect place to redirect the user to the login screen.

// Example: Global invalid session handler
auth.token.onInvalidSession(() => {
  console.log("Session expired! Logging out...");
  // Clear local app state and navigate to Login
});

// Example: Using the token manually
const jwt = await auth.token.get();