AuthSafe TypeScript SDK

The core TypeScript/JavaScript SDK for AuthSafe — a secure, framework-agnostic browser library for OAuth 2.1 and OpenID Connect (OIDC) authentication.

Overview

authsafe-ts is the foundational library that powers framework-specific SDKs like authsafe-react. Use this package when you need direct OAuth/OIDC integration without framework dependencies, or when building custom integrations for Vue, Angular, Svelte, or vanilla JavaScript applications.

Features

• ✅ Framework Agnostic - Works with any JavaScript/TypeScript application
• ✅ OAuth 2.1 & OIDC Compliant - Full implementation using oidc-client-ts
• ✅ PKCE Support - Automatic Proof Key for Code Exchange
• ✅ Token Management - Access tokens, refresh tokens, and ID tokens
• ✅ TypeScript First - Comprehensive type definitions included
• ✅ API Clients - Ready-to-use clients for MFA, SSO, User, and Branding APIs
• ✅ Secure Storage - sessionStorage for OIDC state, HTTP-only cookies for refresh tokens
• ✅ Tree-Shakeable - Import only what you need

Installation

npm install authsafe-ts

Or with other package managers:

# Yarn
yarn add authsafe-ts

# pnpm
pnpm add authsafe-ts

Quick Start

Basic OAuth Authentication

import { OAuthService } from 'authsafe-ts';

// Initialize OAuth service
const oauth = new OAuthService({
  clientId: 'your-client-id',
  redirectUri: 'http://localhost:3000/callback',
  scope: ['openid', 'email', 'profile', 'offline_access'],
  authority: 'https://your-authsafe-domain.com',
  env: 'development',
});

// Initiate login
await oauth.signinRedirect();

// Handle callback
const user = await oauth.signinRedirectCallback();
console.log('Authenticated user:', user);

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

// Logout
await oauth.signoutRedirect();

Using API Clients

import { HttpService, MfaApi, UserApi, BrandingApi, SSOApi } from 'authsafe-ts';

// Create HTTP service with authentication token
const httpService = new HttpService(accessToken);

// MFA Management
const mfaApi = new MfaApi(httpService);
const methods = await mfaApi.listMethods();
const registration = await mfaApi.registerMethod({ type: MfaType.TOTP });
await mfaApi.confirmMethod({ type: MfaType.TOTP, token: '123456' });

// User Management
const userApi = new UserApi(httpService);
await userApi.updateUser(userId, { name: 'John Doe' });

// Branding
const brandingApi = new BrandingApi(httpService);
const branding = await brandingApi.getBranding(clientId);

// SSO
const ssoApi = new SSOApi(httpService);
const providers = await ssoApi.getProviders();

Password Strength Validation

import { calculatePasswordStrength } from 'authsafe-ts';

const result = calculatePasswordStrength('MyP@ssw0rd123');
console.log(result);
// { strength: 80, label: 'Good', color: '#3b82f6' }

Core Exports

Services

• OAuthService - OAuth 2.1/OIDC authentication service
• HttpService - HTTP client with authentication support

API Clients

• MfaApi - Multi-factor authentication management
• UserApi - User profile and account management
• BrandingApi - Client branding configuration
• SSOApi - Single sign-on provider management

Types

All TypeScript types are exported, including:

• User, AuthConfig, AuthTokens, AuthScope
• MfaType, MfaMethod, RegisterMfaRequest, ConfirmMfaRequest
• UpdateUserRequest, Branding, SSO, SSOProvider

Utilities

• calculatePasswordStrength - Password strength calculator

Usage with Frameworks

While you can use this library directly, we provide framework-specific SDKs for better integration:

React

npm install authsafe-react

See the authsafe-react documentation for React-specific hooks and components.

Vue, Angular, Svelte

Use authsafe-ts directly and build your own framework wrappers using the core services and API clients.

TypeScript Support

This library is written in TypeScript and includes comprehensive type definitions:

import type {
  User,
  AuthConfig,
  AuthTokens,
  MfaType,
  MfaMethod,
  Branding,
  SSO,
} from 'authsafe-ts';

Browser Compatibility

• Chrome/Edge: Latest 2 versions
• Firefox: Latest 2 versions
• Safari: Latest 2 versions
• Modern browsers with ES2022 support

Dependencies

• oidc-client-ts - OpenID Connect client
• axios - HTTP client
• js-cookie - Cookie management
• @simplewebauthn/browser - WebAuthn support

License

MIT

Support

For issues, questions, or contributions, please visit:

• GitHub: authsafe/authsafe-js
• Documentation: docs.authsafe.com

Made with ❤️ by the AuthSafe team