@autonomous2026/auth-sdk

Client SDK for auth-service SSO OAuth2 flow with PKCE support.

Installation

npm install @autonomous2026/auth-sdk

Or link locally:

cd sdk && npm install && npm run build
cd .. && npm link ./sdk

Quick Start (React)

1. Wrap your app with AuthProvider

import { AuthProvider } from "@autonomous2026/auth-sdk/react";

const authConfig = {
  ssoUrl: "https://sso.example.com",
  clientId: "my-app",
  redirectUri: "https://app.example.com/callback",
  scope: "openid profile email",
};

function App() {
  return (
    <AuthProvider config={authConfig}>
      <YourApp />
    </AuthProvider>
  );
}

2. Use the hooks

import { useAuth, useUser } from "@autonomous2026/auth-sdk/react";

function LoginButton() {
  const { isAuthenticated, login, logout, isLoading } = useAuth();

  if (isLoading) return <div>Loading...</div>;

  if (isAuthenticated) {
    return <button onClick={() => logout()}>Logout</button>;
  }

  return <button onClick={() => login()}>Login with SSO</button>;
}

function UserProfile() {
  const user = useUser();

  if (!user) return null;

  return (
    <div>
      <p>Welcome, {user.fullName || user.email}!</p>
    </div>
  );
}

3. Handle OAuth2 callback

import { useAuthCallback } from "@autonomous2026/auth-sdk/react";
import { useNavigate } from "react-router-dom";

function CallbackPage() {
  const navigate = useNavigate();
  const { isLoading, error, success } = useAuthCallback(authConfig);

  useEffect(() => {
    if (success) {
      navigate("/dashboard");
    }
  }, [success, navigate]);

  if (isLoading) return <div>Processing login...</div>;
  if (error) return <div>Login failed: {error}</div>;

  return null;
}

Vanilla JavaScript Usage

import { AuthClient } from "@autonomous2026/auth-sdk";

const client = new AuthClient({
  ssoUrl: "https://sso.example.com",
  clientId: "my-app",
  redirectUri: "https://app.example.com/callback",
  scope: "openid profile email",
});

// Start login
await client.authorize();

// Handle callback (on callback page)
const result = await client.handleCallback(code, state);
if (result.success) {
  console.log("Logged in!", result.tokens);
}

// Check auth status
if (client.isAuthenticated()) {
  const user = client.getUser();
  console.log("User:", user);
}

// Get access token (auto-refreshes if expired)
const token = await client.getValidAccessToken();

// Logout
client.logout();

API Reference

AuthClient

| Method | Description | | ----------------------------- | ------------------------------- | | authorize(options?) | Start OAuth2 login flow | | handleCallback(code, state) | Exchange code for tokens | | refreshToken() | Refresh access token | | logout(redirectUri?) | Logout and redirect to SSO | | isAuthenticated() | Check if user is logged in | | getAccessToken() | Get current access token | | getUser() | Get decoded user from JWT | | getValidAccessToken() | Get token, refresh if expired | | clearTokens() | Clear tokens without SSO logout |

AuthorizeOptions

| Option | Type | Description | | ----------- | --------------------------------------- | -------------------------------------- | | prompt | 'select_account' \| 'none' \| 'login' | Force account selection or silent auth | | loginHint | string | Pre-fill email for login |

User Object

| Field | Type | Description | | --------------- | ----------- | --------------- | | id | string | User ID | | email | string | User email | | fullName | string? | Full name | | roles | string[]? | User roles | | companyDomain | string? | Company domain | | isEppUser | boolean? | EPP user status |

React Hooks

| Hook | Returns | Description | | ------------------------- | ------------------ | ---------------------- | | useAuth() | AuthContextValue | Auth state and actions | | useUser() | User \| null | Current user info | | useAuthCallback(config) | Callback state | Handle OAuth2 callback |

AuthProvider Props

| Prop | Type | Default | Description | | --------------- | ------------ | -------- | -------------------------------- | | config | AuthConfig | required | Auth configuration | | autoRefresh | boolean | true | Auto-refresh tokens | | refreshBuffer | number | 60 | Seconds before expiry to refresh | | onAuthChange | function | - | Callback on auth state change |

Custom Storage

By default, tokens are stored in localStorage. You can provide a custom storage:

const client = new AuthClient({
  ...config,
  storage: {
    getItem: (key) => sessionStorage.getItem(key),
    setItem: (key, value) => sessionStorage.setItem(key, value),
    removeItem: (key) => sessionStorage.removeItem(key),
  },
});

Security

• Uses PKCE (S256) to prevent authorization code interception
• State parameter for CSRF protection
• PKCE verifier stored in sessionStorage (not localStorage)
• Automatic token refresh before expiry