@drmhse/sso-sdk 0.2.4 → 0.2.6

package/README.md

@@ -1,15 +1,24 @@
 # SSO Platform SDK
 
-A zero-dependency, strongly-typed TypeScript SDK for interacting with the multi-tenant SSO Platform API.
+[![npm version](https://img.shields.io/npm/v/@drmhse/sso-sdk)](https://www.npmjs.com/package/@drmhse/sso-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+A zero-dependency, strongly-typed TypeScript SDK for the multi-tenant SSO Platform API.
+
+**📚 [View Full Documentation →](https://drmhse.com/docs/sso/)**
 
 ## Features
 
--   **Zero Dependencies**: Built on native `fetch` API - no external dependencies.
--   **Framework Agnostic**: Pure TypeScript - works in any JavaScript environment.
--   **Strongly Typed**: Complete TypeScript definitions for all API endpoints.
--   **Stateless Design**: No internal state management - integrates with any state solution.
--   **Predictable Error Handling**: Custom `SsoApiError` class with structured error information.
--   **Modern**: Supports Node.js 18+ and all modern browsers.
+- ✅ **Zero Dependencies** - Built on native `fetch` API
+- ✅ **Strongly Typed** - Complete TypeScript definitions
+- ✅ **Framework Agnostic** - Works in any JavaScript environment
+- ✅ **OAuth 2.0 Flows** - Support for GitHub, Google, Microsoft
+- ✅ **Password Authentication** - Native email/password auth with MFA
+- ✅ **Device Flow** - RFC 8628 for CLIs and headless apps
+- ✅ **Multi-Factor Authentication** - TOTP-based 2FA with backup codes
+- ✅ **Organization Management** - Multi-tenant with RBAC
+- ✅ **Analytics & Audit Logs** - Track authentication and administrative actions
+- ✅ **SAML 2.0** - Act as Identity Provider
 
 ## Installation
 
@@ -20,38 +29,37 @@ npm install @drmhse/sso-sdk
 ## Quick Start
 
 ```typescript
-import { SsoClient, SsoApiError } from '@drmhse/sso-sdk';
+import { SsoClient } from '@drmhse/sso-sdk';
 
 // Initialize the client
 const sso = new SsoClient({
   baseURL: 'https://sso.example.com',
-  token: localStorage.getItem('sso_token') // Optional initial token
+  token: localStorage.getItem('sso_access_token')
 });
 
-// Use the SDK
-async function example() {
-  try {
-    // Get user profile
-    const profile = await sso.user.getProfile();
-    console.log(profile.email);
+// Get user profile
+const profile = await sso.user.getProfile();
+console.log(profile.email);
 
-    // List organizations
-    const orgs = await sso.organizations.list();
-    console.log(orgs);
-  } catch (error) {
-    if (error instanceof SsoApiError) {
-      console.error(`API Error: ${error.message} (${error.errorCode})`);
-    }
-  }
-}
+// List organizations
+const orgs = await sso.organizations.list();
+console.log(orgs);
 ```
 
-## Authentication Flows
+**New to the SDK?** Start with the **[Getting Started Guide →](https://drmhse.com/docs/sso/sdk/getting-started)** for a step-by-step tutorial showing how to authenticate users from scratch, handle token refresh, and implement logout.
 
-### End-User OAuth Login
+**Essential Guides:**
+- **[Authentication Flows](https://drmhse.com/docs/sso/sdk/guides/authentication-flows)** - OAuth, Device Flow, and Admin Login patterns
+- **[Password Authentication](https://drmhse.com/docs/sso/sdk/guides/password-authentication)** - Registration, login, and password reset
+- **[MFA Management](https://drmhse.com/docs/sso/sdk/guides/mfa-management)** - TOTP-based 2FA implementation
+- **[Error Handling](https://drmhse.com/docs/sso/sdk/guides/error-handling)** - Best practices for handling API errors
+
+## Authentication Examples
+
+### OAuth Login
 
 ```typescript
-// 1. Redirect user to OAuth provider
+// Redirect to OAuth provider
 const loginUrl = sso.auth.getLoginUrl('github', {
   org: 'acme-corp',
   service: 'main-app',
@@ -59,393 +67,290 @@ const loginUrl = sso.auth.getLoginUrl('github', {
 });
 window.location.href = loginUrl;
 
-// 2. In your callback handler, extract both tokens from the URL
+// Handle callback
 const params = new URLSearchParams(window.location.search);
 const accessToken = params.get('access_token');
 const refreshToken = params.get('refresh_token');
 
 if (accessToken && refreshToken) {
   sso.setAuthToken(accessToken);
-  localStorage.setItem('sso_token', accessToken);
+  localStorage.setItem('sso_access_token', accessToken);
   localStorage.setItem('sso_refresh_token', refreshToken);
 }
 ```
 
-### Admin Login
+### Password Authentication
 
 ```typescript
-const adminUrl = sso.auth.getAdminLoginUrl('github', {
-  org_slug: 'acme-corp' // Optional: directs user to a specific org dashboard after login
+// Register new user
+await sso.auth.register({
+  email: 'user@example.com',
+  password: 'SecurePass123!',
+  org_slug: 'acme-corp'
 });
-window.location.href = adminUrl;
+
+// Login with password
+const tokens = await sso.auth.login({
+  email: 'user@example.com',
+  password: 'SecurePass123!'
+});
+sso.setAuthToken(tokens.access_token);
+
+// Enable MFA
+const mfaSetup = await sso.user.mfa.setup();
+console.log(mfaSetup.qr_code); // Display QR code to user
+
+// Verify and enable
+await sso.user.mfa.verify('123456'); // TOTP code from authenticator app
 ```
 
 ### Device Flow (for CLIs)
 
-This flow involves both the CLI and a web browser.
-
 ```typescript
-// --- In your CLI Application ---
-
-// 1. Request device code
+// In your CLI application
 const deviceAuth = await sso.auth.deviceCode.request({
-  client_id: 'cli-client-id',
+  client_id: 'cli-client',
   org: 'acme-corp',
-  service: 'acme-cli'
+  service: 'cli-tool'
 });
 
 console.log(`Visit: ${deviceAuth.verification_uri}`);
 console.log(`Enter code: ${deviceAuth.user_code}`);
 
-// 4. Poll for the token
-const pollForToken = async () => {
-  // Polling logic...
-};
-pollForToken();
-
-
-// --- In your Web Application at /activate ---
-
-// 2. After user enters the code, verify it to get context
-const context = await sso.auth.deviceCode.verify(userEnteredCode);
+// Poll for token
+const interval = setInterval(async () => {
+  try {
+    const tokens = await sso.auth.deviceCode.exchangeToken({
+      device_code: deviceAuth.device_code,
+      client_id: 'cli-client'
+    });
 
-// 3. Redirect user to the appropriate login flow, passing the user_code
-// This links the browser session to the device waiting for authorization.
-const loginUrl = sso.auth.getLoginUrl('github', { 
-  org: context.org_slug,
-  service: context.service_slug,
-  user_code: userEnteredCode, // CRITICAL: Pass user_code here
-});
-window.location.href = loginUrl; // User logs in, authorizing the device
+    sso.setAuthToken(tokens.access_token);
+    clearInterval(interval);
+    console.log('✓ Authentication successful!');
+  } catch (error) {
+    // Continue polling...
+  }
+}, deviceAuth.interval * 1000);
 ```
 
-### Refreshing Tokens
-
-Renew an expired access token using a refresh token. This uses token rotation for enhanced security.
+### Token Refresh
 
 ```typescript
 try {
   const tokens = await sso.auth.refreshToken(storedRefreshToken);
-  
-  // Update tokens in your application state and storage
+
   sso.setAuthToken(tokens.access_token);
-  localStorage.setItem('sso_token', tokens.access_token);
+  localStorage.setItem('sso_access_token', tokens.access_token);
   localStorage.setItem('sso_refresh_token', tokens.refresh_token);
 } catch (error) {
-  // Refresh failed, user needs to log in again
-  console.error("Token refresh failed:", error);
+  // Refresh failed - redirect to login
+  console.error('Token refresh failed:', error);
 }
 ```
 
-### Logout
+## Organization Management
 
 ```typescript
-await sso.auth.logout();
-sso.setAuthToken(null);
-localStorage.removeItem('sso_token');
-localStorage.removeItem('sso_refresh_token');
-```
-
-## Validating Tokens in Your Backend
-
-The SSO platform uses **RS256** (RSA with SHA-256) asymmetric signing for JWTs. This means your backend services can validate JWT signatures without needing access to any shared secrets.
-
-### How It Works
-
-1. **Fetch the JWKS**: The SSO platform exposes a public JWKS (JSON Web Key Set) endpoint at `/.well-known/jwks.json` containing the public RSA key(s).
-2. **Cache the Keys**: Fetch and cache the JWKS in your backend to avoid repeated requests.
-3. **Verify Tokens**: When a client sends a JWT, extract the `kid` (Key ID) from the token header, find the matching key in your cached JWKS, and verify the signature.
-4. **Validate Claims**: After signature verification, validate token claims like `exp` (expiration), `iss` (issuer), and `aud` (audience).
-
-### Node.js/Express Example
-
-Here's a complete example of JWT validation middleware:
-
-```typescript
-import { expressjwt } from 'express-jwt';
-import jwksRsa from 'jwks-rsa';
-
-// Configure JWKS client to fetch public keys
-const jwksClient = jwksRsa({
-  cache: true,
-  rateLimit: true,
-  jwksRequestsPerMinute: 5,
-  jwksUri: 'https://sso.example.com/.well-known/jwks.json'
+// Create organization
+const org = await sso.organizations.createPublic({
+  name: 'Acme Corp',
+  slug: 'acme-corp'
 });
 
-// Function to get signing key from JWKS
-function getKey(header, callback) {
-  jwksClient.getSigningKey(header.kid, (err, key) => {
-    if (err) {
-      return callback(err);
-    }
-    const signingKey = key.getPublicKey();
-    callback(null, signingKey);
-  });
-}
+// Configure custom OAuth (BYOO - Bring Your Own OAuth)
+await sso.organizations.oauthCredentials.set('acme-corp', 'github', {
+  client_id: 'your-github-client-id',
+  client_secret: 'your-github-client-secret'
+});
 
-// JWT validation middleware
-const requireAuth = expressjwt({
-  secret: getKey,
-  algorithms: ['RS256'],
-  credentialsRequired: true,
-  getToken: (req) => {
-    if (req.headers.authorization?.startsWith('Bearer ')) {
-      return req.headers.authorization.substring(7);
-    }
-    return null;
-  }
+// Invite team members
+await sso.organizations.invitations.create('acme-corp', {
+  email: 'member@acme.com',
+  role: 'admin'
 });
 
-// Use in your routes
-app.get('/api/protected', requireAuth, (req, res) => {
-  // req.auth contains the decoded JWT claims
-  const { sub, email, org, service } = req.auth;
-  res.json({ message: `Hello ${email}` });
+// Configure SMTP for transactional emails
+await sso.organizations.setSmtp('acme-corp', {
+  host: 'smtp.gmail.com',
+  port: 587,
+  username: 'noreply@acme.com',
+  password: 'app-password',
+  from_email: 'noreply@acme.com',
+  from_name: 'Acme Corp'
 });
 ```
 
-### Manual Validation (Node.js)
-
-If you prefer to validate manually without middleware:
+## Services & API Keys
 
 ```typescript
-import jwt from 'jsonwebtoken';
-import jwksRsa from 'jwks-rsa';
-
-const jwksClient = jwksRsa({
-  jwksUri: 'https://sso.example.com/.well-known/jwks.json'
+// Create a service
+const service = await sso.services.create('acme-corp', {
+  name: 'Main Application',
+  slug: 'main-app',
+  redirect_uris: ['https://app.acme.com/callback']
 });
 
-async function validateToken(token: string) {
-  try {
-    // Decode without verifying to get the kid
-    const decoded = jwt.decode(token, { complete: true });
-    if (!decoded || !decoded.header.kid) {
-      throw new Error('Invalid token: missing kid');
-    }
-
-    // Get the public key for this kid
-    const key = await jwksClient.getSigningKey(decoded.header.kid);
-    const publicKey = key.getPublicKey();
+// Create API key for service-to-service auth
+const apiKey = await sso.services.apiKeys.create('acme-corp', 'main-app', {
+  name: 'Production Backend',
+  expires_at: '2026-01-01T00:00:00Z'
+});
 
-    // Verify and decode the token
-    const verified = jwt.verify(token, publicKey, {
-      algorithms: ['RS256']
-    });
+console.log('API Key (save this):', apiKey.key);
 
-    return verified; // Returns the decoded claims
-  } catch (error) {
-    console.error('Token validation failed:', error);
-    throw error;
-  }
-}
-
-// Usage
-const claims = await validateToken(req.headers.authorization.split(' ')[1]);
-console.log(claims.email, claims.org, claims.service);
+// Use API key for backend authentication
+const backendClient = new SsoClient({
+  baseURL: 'https://sso.example.com',
+  apiKey: apiKey.key
+});
 ```
 
-### Other Languages
-
-The same approach works in any language:
-
-- **Python**: Use `PyJWT` with `python-jose` or `jwcrypto`
-- **Go**: Use `golang-jwt/jwt` with JWKS support
-- **Java**: Use `java-jwt` or Spring Security with JWKS
-- **Ruby**: Use `jwt` gem with `jwks-ruby`
-
-The key steps are always the same:
-1. Fetch JWKS from `/.well-known/jwks.json`
-2. Extract `kid` from JWT header
-3. Find matching key in JWKS
-4. Verify signature using the public key
-5. Validate token claims (especially `exp`)
-
-## API Reference
-
-### Analytics (`sso.analytics`)
-
-Provides login tracking and metrics for a specific organization.
+## Analytics
 
 ```typescript
-// Get login trends over time
+// Get login trends
 const trends = await sso.analytics.getLoginTrends('acme-corp', {
   start_date: '2025-01-01',
   end_date: '2025-01-31'
 });
-```
-
-### Authentication (`sso.auth`)
-
-Handles all authentication flows, including OAuth, device flow, and token management.
 
-```typescript
-// Get a fresh OAuth token for an external provider (e.g., GitHub)
-const githubToken = await sso.auth.getProviderToken('github');
-// Use githubToken.access_token to make GitHub API calls
-```
-
-### Organizations (`sso.organizations`)
+// Get provider distribution
+const byProvider = await sso.analytics.getLoginsByProvider('acme-corp');
+console.log(byProvider); // [{ provider: 'github', count: 1523 }, ...]
 
-Manages organizations, members, and BYOO credentials.
-
-```typescript
-// Create organization (public endpoint)
-const org = await sso.organizations.createPublic({
-  slug: 'acme-corp',
-  name: 'Acme Corporation',
-  owner_email: 'founder@acme.com'
-});
-
-// BYOO: Set custom OAuth credentials
-await sso.organizations.oauthCredentials.set('acme-corp', 'github', {
-  client_id: 'Iv1.abc123',
-  client_secret: 'secret-value'
+// Get recent activity
+const recentLogins = await sso.analytics.getRecentLogins('acme-corp', {
+  limit: 20
 });
 ```
 
-#### End-User Management (`sso.organizations.endUsers`)
-
-Manage your organization's customers (end-users who have logged in or have subscriptions).
+## Error Handling
 
 ```typescript
-// List all end-users across all services
-const allUsers = await sso.organizations.endUsers.list('acme-corp', {
-  page: 1,
-  limit: 20
-});
-
-// Filter end-users by a specific service
-const serviceUsers = await sso.organizations.endUsers.list('acme-corp', {
-  service_slug: 'main-app',
-  page: 1,
-  limit: 20
-});
+import { SsoClient, SsoApiError } from '@drmhse/sso-sdk';
 
-// Get detailed information about a specific end-user
-const user = await sso.organizations.endUsers.get('acme-corp', 'user-id-123');
-console.log(`Active sessions: ${user.session_count}`);
+try {
+  await sso.user.getProfile();
+} catch (error) {
+  if (error instanceof SsoApiError) {
+    console.error(`API Error: ${error.message}`);
+    console.error(`Status: ${error.status}`);
+    console.error(`Code: ${error.errorCode}`);
 
-// Revoke all active sessions for a specific end-user (force logout)
-await sso.organizations.endUsers.revokeSessions('acme-corp', 'user-id-123');
+    if (error.status === 401) {
+      // Token expired - refresh or re-authenticate
+    } else if (error.status === 403) {
+      // Forbidden - insufficient permissions
+    }
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
 ```
 
-### Services & Plans (`sso.services`)
+## Platform Administration
 
-Manages the applications (services) and subscription plans for an organization.
+For platform owners managing the entire SSO system:
 
 ```typescript
-// Create a service
-const result = await sso.services.create('acme-corp', {
-  slug: 'main-app',
-  name: 'Main Application',
-  service_type: 'web',
-  redirect_uris: ['https://app.acme.com/callback']
+// Approve pending organization
+await sso.platform.organizations.approve('org-id', {
+  tier: 'professional',
+  reason: 'Verified enterprise customer'
 });
 
-// Create a subscription plan for that service
-await sso.services.plans.create('acme-corp', 'main-app', {
-  name: 'pro',
-  price_cents: 2999, // Note: price is in cents
-  currency: 'usd',
-  features: ['api-access', 'priority-support']
+// Promote user to platform owner
+await sso.platform.promoteOwner({
+  email: 'admin@example.com'
 });
+
+// Get platform analytics
+const overview = await sso.platform.analytics.getOverview();
+console.log(overview); // { total_users, total_orgs, total_logins, ... }
+
+// Search users across all organizations
+const users = await sso.platform.users.search('user@example.com');
 ```
 
-### User Profile & Identities (`sso.user`)
+## TypeScript Support
 
-Manages the authenticated user's own profile and linked social accounts.
+The SDK is written in TypeScript and includes complete type definitions:
 
 ```typescript
-// Get profile
-const profile = await sso.user.getProfile();
+import type {
+  User,
+  Organization,
+  Service,
+  LoginTrendPoint,
+  RefreshTokenResponse,
+  CreateServicePayload,
+  UpdateServicePayload,
+  LoginPayload,
+  RegisterPayload,
+  SsoApiError
+} from '@drmhse/sso-sdk';
 
-// Start linking a new social account
-const { authorization_url } = await sso.user.identities.startLink('google');
-window.location.href = authorization_url;
+// Example using types
+const createService = async (payload: CreateServicePayload): Promise<Service> => {
+  return await sso.services.create('org-slug', payload);
+};
 
-// Unlink a social account
-await sso.user.identities.unlink('github');
+const login = async (credentials: LoginPayload): Promise<RefreshTokenResponse> => {
+  return await sso.auth.login(credentials);
+};
 ```
 
-### Invitations (`sso.invitations`)
+## Validating JWTs in Your Backend
 
-Manages team invitations for an organization.
+The SSO platform uses RS256 (asymmetric) JWT signing. Your backend can validate tokens without sharing secrets:
 
 ```typescript
-// Create and send an invitation
-await sso.invitations.create('acme-corp', {
-  email: 'new-dev@example.com',
-  role: 'member'
-});
+// Fetch JWKS from the SSO platform
+const jwksUrl = 'https://sso.example.com/.well-known/jwks.json';
+const response = await fetch(jwksUrl);
+const jwks = await response.json();
 
-// List invitations for the current user
-const myInvites = await sso.invitations.listForUser();
-```
-
-### Platform Administration (`sso.platform`)
-
-Platform owner methods require a Platform Owner JWT.
+// Use a JWT library to verify tokens
+import jwt from 'jsonwebtoken';
+import jwksClient from 'jwks-rsa';
 
-```typescript
-// List all organizations awaiting approval
-const pendingOrgs = await sso.platform.organizations.list({
-  status: 'pending'
-});
+const client = jwksClient({ jwksUri: jwksUrl });
+const key = await client.getSigningKey(header.kid);
+const publicKey = key.getPublicKey();
 
-// Approve an organization
-await sso.platform.organizations.approve('org-id-123', {
-  tier_id: 'tier-starter'
+const decoded = jwt.verify(token, publicKey, {
+  algorithms: ['RS256']
 });
 ```
 
-#### Platform Analytics (`sso.platform.analytics`)
+**📚 [See Backend Validation Guide →](https://drmhse.com/docs/sso/api/concepts/token-validation)**
 
-Provides platform-wide metrics for platform owners.
+## Documentation
 
-```typescript
-// Get platform-wide analytics overview
-const overview = await sso.platform.analytics.getOverview();
-console.log(`Total Users: ${overview.total_users}`);
-```
+**[Complete documentation is available at drmhse.com/docs/sso](https://drmhse.com/docs/sso/)**
 
-## Error Handling
+### Key Documentation Pages
 
-The SDK throws `SsoApiError` for all API errors:
+- **[Getting Started](https://drmhse.com/docs/sso/sdk/getting-started)** - Installation and setup
+- **[Authentication Flows](https://drmhse.com/docs/sso/sdk/guides/authentication-flows)** - OAuth, Device Flow, Admin Login
+- **[Password Authentication](https://drmhse.com/docs/sso/sdk/guides/password-authentication)** - Register, Login, Reset Password
+- **[MFA Management](https://drmhse.com/docs/sso/sdk/guides/mfa-management)** - TOTP setup and verification
+- **[SDK Reference](https://drmhse.com/docs/sso/sdk/reference)** - Complete API reference
+- **[API Reference](https://drmhse.com/docs/sso/api/reference)** - Backend API documentation
 
-```typescript
-import { SsoApiError } from '@drmhse/sso-sdk';
+## Requirements
 
-try {
-  await sso.organizations.get('non-existent');
-} catch (error) {
-  if (error instanceof SsoApiError) {
-    console.error(`Error ${error.statusCode}: ${error.message}`);
-    console.error(`Code: ${error.errorCode}`);
+- **Node.js:** 18+ (for native fetch support)
+- **Browsers:** All modern browsers with fetch support
+- **TypeScript:** 4.5+ (optional, but recommended)
 
-    if (error.isAuthError()) {
-      // Redirect to login
-    }
-  }
-}
-```
-
-## TypeScript
+## License
 
-The SDK is written in TypeScript and includes complete type definitions.
+MIT © [DRM HSE](https://github.com/drmhse)
 
-```typescript
-import type {
-  Organization,
-  Service,
-  User,
-  JwtClaims,
-  SsoApiError,
-  // ... and many more types
-} from '@drmhse/sso-sdk';
-```
-
-## License
+## Support
 
-MIT
+- **Documentation:** [drmhse.com/docs/sso](https://drmhse.com/docs/sso/)
+- **Issues:** [GitHub Issues](https://github.com/drmhse/sso/issues)
+- **Email:** [info@drmhse.com](mailto:info@drmhse.com)