@authspherejs/sdk
v1.1.3TypeScript
Secure OAuth2 SDK with PKCE for AuthSphere authentication
0/weekUpdated 6 days agoMITUnpacked: 72.0 KB
Published by AuthSphere Team
npm install @authspherejs/sdk
# 🌐 AuthSphere SDK
The ultimate TypeScript engine for secure, enterprise-grade authentication.
Features •
Quick Start •
Configuration •
Security •
API Reference
---
✨ Features
🛡️ Secure by Design
Built-in OAuth2 with PKCE (Proof Key for Code Exchange) to prevent authorization code injection and man-in-the-middle attacks.
🔌 Multi-Provider
Seamless support for Google, GitHub, and Discord out of the box. Unified interface for all providers.
🔄 Session Management
Automated JWT handling, secure token persistence (localStorage/SessionStorage), and ready-to-use logout flows.
🔐 Local Auth
Complete Email/Password system with built-in OTP verification and email lifecycle management.
🏗️ Type Safe
Written in TypeScript. Full IDE support, IntelliSense, and comprehensive type definitions for every flow.
---
📺 Demo
Standard authentication flow: Redirect -> login -> Token Exchange -> Session
---
🚀 Installation
Install the package via your favorite package manager:
``
bash
npm
npm install @authspherejs/sdk
pnpm
pnpm add @authspherejs/sdk
yarn
yarn add @authspherejs/sdk
`
---
🛠️ Quick Start
$3
Initialize the client at the root of your application (e.g., in main.ts or App.tsx).
`typescript
import AuthSphere from "@authspherejs/sdk";
AuthSphere.initAuth({
publicKey: "your_project_public_key",
redirectUri: "http://localhost:3000/callback",
baseUrl: "https://api.authsphere.dev", // Your AuthSphere backend URL
});
`
$3
Redirect users to their preferred OAuth provider with a single function call.
`typescript
// Support for 'google', 'github', 'discord'
const login = (provider: "google" | "github" | "discord") => {
AuthSphere.redirectToLogin(provider);
};
`
$3
Create a route for your redirectUri (e.g., /callback) to process the exchange.
`typescript
async function handleCallback() {
try {
const session = await AuthSphere.handleAuthCallback();
console.log("User signed in:", session.user);
window.location.href = "/dashboard";
} catch (error) {
console.error("Authentication failed:", error);
}
}
`
$3
For apps requiring custom signup flows with email verification. The SDK handles the heavy lifting of state preservation across redirects.
`typescript
// 1. Register User
await AuthSphere.register({
email: "dev@example.com",
password: "Password123!",
username: "Madhav",
});
// 2. Login Attempt
try {
const session = await AuthSphere.loginLocal({ email, password });
// If verified, session is established immediately
} catch (err) {
if (err.error_code === "EMAIL_NOT_VERIFIED") {
// Navigator to your verification UI
// The 'sdk_request' preserves the original OIDC context
const { sdk_request } = err.metadata;
navigate(/verify?email=${email}&sdk_request=${sdk_request});
}
}
// 3. Verify Challenge (OTP)
// On success, the SDK automatically resolves the pending login
await AuthSphere.verifyOTP({
email: "dev@example.com",
otp: "123456",
sdk_request: "...", // Pass the ID from the login error meta
});
`
---
📖 API Reference
$3
Initializes the SDK with your project settings.
$3
Initiates the OAuth2 PKCE flow for the specified provider.
$3
Exchanges the authorization code for a session token. Returns a Promise.
$3
Registers a new user and triggers the verification email.
$3
Authenticates with email/password. Throws AuthError if verification is required.
$3
Verifies a 6-digit code. Can perform an automatic login if sdk_request is provided.
$3
Requests a new 6-digit verification code for the specified email.
$3
Checks if a valid session exists in storage.
$3
Returns the profile information of the currently logged-in user.
$3
Clears the session data and terminates the user session.
---
🔧 Configuration Options
| Option | Type | Required | Description |
| :------------ | :--------- | :------: | :------------------------------------------------------ |
| publicKey | string | Yes | Your project's Identification Key from the dashboard. |
| redirectUri | string | Yes | The URI your app redirects back to after auth. |
| baseUrl | string | No | Your API server URL (Default: http://localhost:8000). |
| onAuthError | Function | No | Global hook for handling authentication errors. |
---
🛡️ Security Note
AuthSphere implements the Authorization Code Flow with PKCE, the gold standard for securing public clients (SPAs/Mobile Apps).
> [!IMPORTANT]
> This flow ensures that even if an authorization code is intercepted, it cannot be exchanged for a token without the original client's cryptographically generated "code verifier".
---
📄 License
Distributed under the MIT License. See LICENSE` for more information.