Skip to content
rw3iss Auth

auth-client overview

@rw3iss/auth-client is the browser SDK. Vanilla TypeScript core with first-class adapters for React, Preact, SolidJS, Vue, and Astro. Hexagonal architecture — every external dependency is an injectable port with a browser-native default.

Sourcerw3iss/auth-client
Live demodemo.auth.ryanweiss.net
Companionauth-shared (types)

Highlights

  • Same API everywhere. Every adapter exposes useAuth, useLogin, useStartSso, … — switching frameworks is a one-line import change.
  • Three bootstrap modes.
    • auto (default): proactively validates the cached session against /auth/me at boot. UIs gate their first render on ready().
    • lazy: trusts cached claims, defers validation until the first failed request.
    • offline: inert mode. Flow methods throw OfflineModeError.
  • Auto-retry on 401. authenticatedRequest() refreshes under a mutex and retries once. Refresh failure clears state + emits session_expired.
  • Cross-tab session sync. BroadcastChannel keeps every tab consistent.
  • Refresh-mutex coalescing. A burst of N concurrent requests just-before-expiry triggers ONE refresh, not N.
  • Pluggable everything. Token store, transport, storage, clock, crypto, logger, broadcast — each is a port.
  • Full server feature parity. Password + SSO/PKCE, TOTP 2FA, refresh-rotation, dual-secret rotation, impersonation, hard-delete, per-user token-version, org / app context switching.

The 80% usage

import { createAuthClient } from '@rw3iss/auth-client';


const auth = createAuthClient({
    apiBaseUrl: 'https://auth.ryanweiss.net/api/v1',
    appCode: 'marketplace-buyer',
});


await auth.ready();
if (auth.isAuthenticated()) {
    console.log('signed in as', auth.getCurrentUser());
} else {
    await auth.loginWithPassword({ email, password });
}


auth.on('logged_out', () => router.push('/login'));

See Quickstart for the full pattern.

The module API

The SDK surface is organized into namespaced modules — stateless method groups over the one client core, which owns all auth context, token storage and refresh:

ModulePurpose
client.authlogin (password / SSO / magic link), register, logout(-all), refresh, switchOrg, whoami, identity getters
client.accountown password, email verification, 2FA, memberships, invitations, delete-my-account
client.sessionsown device sessions
client.usersadmin user administration (roles, sessions, impersonate, hard delete)
client.organizationsorg CRUD, members, custom roles, invitations
client.appsapplication registry (pools, policy, webhooks) + user access grants
client.servicesm2m machine-credential registry
client.poolsuser pools (namespaces)
client.auditaudit log
await auth.organizations.addMember(orgId, userId);
await auth.apps.update(appId, { webhooks: [...] });
const pools = await auth.pools.list();

Since v0.3.0 the modules OWN the endpoint implementations — the old flat endpoint methods (auth.listApps(), …) are removed from AuthClient, which keeps only the session engine (lifecycle/state + session-mutating operations like loginWithPassword, logoutAll, switchOrg). Framework hooks are unaffected. Each module class is documented on its own page in the reference (AuthModule, UsersModule, …).

Adapters

FrameworkSubpathSurface
React@rw3iss/auth-client/reactuseAuth, useLogin, useLogout, useVerifyEmail, useRequestMagicLink, useAdminListUserSessions, …
Preact@rw3iss/auth-client/preactSame surface as React. Used by auth-client-demo.
Solid@rw3iss/auth-client/solidSolid stores — same surface.
Vue@rw3iss/auth-client/vueVue composables — same surface.
Astro@rw3iss/auth-client/astroAstro helpers + middleware.

UI components

SubpathWhat’s inside
@rw3iss/auth-client/preact/ui/atoms13 headless primitives — AuthStatusBadge, UserAvatar, UserMenu, LogoutButton, SsoButton, ProtectedRoute, GuestOnly, RoleGate, PermissionGate, TokenExpiryCountdown, AuthLoading.
@rw3iss/auth-client/preact/ui/forms25 composed forms — LoginForm, RegisterForm, PasswordResetRequestForm, TwoFactorEnrollment, SessionsList, MagicLinkRequestForm, DeleteAccountForm, AuditLogTable, UsersTable, AdminUserEditPanel, OrgRoleEditor, …
@rw3iss/auth-client/preact/ui/flows7 end-to-end multi-step flows — CompleteLoginFlow, CompleteSignupFlow, CompletePasswordResetFlow, CompleteSsoCallbackFlow, CompleteAccountSecurityFlow, CompleteImpersonationFlow, CompleteOrgAdminFlow.

See the live catalog at demo.auth.ryanweiss.net.