@drmhse/sso-sdk 0.5.0 → 0.5.1

package/README.md

@@ -1,577 +1,92 @@
-# [AuthOS](https://authos.dev) SDK
+# @drmhse/sso-sdk
 
 [![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 [AuthOS](https://authos.dev), the multi-tenant authentication platform.
+Core TypeScript SDK for AuthOS. It handles authentication flows, session persistence, token refresh, and the multi-tenant API surface used by the framework adapters.
 
-**[View Full Documentation →](https://drmhse.com/docs/sso/)**
+Full documentation: [authos.dev/docs/sdk/](https://authos.dev/docs/sdk/)
 
-## Features
+AI agent skills: [authos.dev/docs/ai-agent-skills/](https://authos.dev/docs/ai-agent-skills/) and [github.com/CkCreative/authos_skill](https://github.com/CkCreative/authos_skill)
 
-- **Zero Dependencies** - Built on native `fetch` API
-- **Strongly Typed** - Complete TypeScript definitions
-- **Framework Agnostic** - Works in any JavaScript environment
-- **Automatic Session Management** - Invisible token persistence and auto-refresh
-- **Smart Token Handling** - Auto-inject tokens and handle 401 errors transparently
-- **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
+## Install
 
 ```bash
 npm install @drmhse/sso-sdk
 ```
 
-## Quick Start
+## Quick start
 
-```typescript
+```ts
 import { SsoClient } from '@drmhse/sso-sdk';
 
-// Initialize the client - automatically loads tokens from localStorage
 const sso = new SsoClient({
-  baseURL: 'https://sso.example.com'
+  baseURL: 'https://sso.example.com',
 });
 
-// Login - session is automatically saved
 await sso.auth.login({
   email: 'user@example.com',
-  password: 'SecurePass123!'
+  password: 'SecurePass123!',
+  org_slug: 'acme-corp',
+  service_slug: 'main-app',
 });
 
-// Make authenticated requests - tokens auto-injected and auto-refreshed
 const profile = await sso.user.getProfile();
 console.log(profile.email);
-
-const orgs = await sso.organizations.list();
-console.log(orgs);
-```
-
-## Understanding Context Modes
-
-AuthOS supports **two initialization modes** that determine how authentication is handled:
-
-### Platform-Level Mode
-
-For platform owners and administrators managing AuthOS itself:
-
-```typescript
-const sso = new SsoClient({
-  baseURL: 'https://sso.example.com'
-});
-
-// Platform-level login (email/password only)
-await sso.auth.login({
-  email: 'admin@platform.com',
-  password: 'SecurePass123!'
-});
-// JWT contains: { is_platform_owner: true, ... }
 ```
 
-**When to use:** Admin dashboards, platform management tools, internal tooling.
-
-### Multi-Tenant Mode
+## Common usage modes
 
-For end-user applications that integrate with AuthOS:
-
-```typescript
-// Initialize with org and service context
-const sso = new SsoClient({
-  baseURL: 'https://sso.example.com'
-});
+### Platform administration
 
-// OAuth redirects require org + service to determine:
-// 1. Which tenant's OAuth credentials (BYOO) to use
-// 2. Which service the identity is attributed to
-const loginUrl = sso.auth.getLoginUrl('github', {
-  org: 'acme-corp',      // Organization slug
-  service: 'main-app',   // Service within that org
-  redirect_uri: 'https://app.acme.com/callback'
-});
+Use only `baseURL` when acting as a platform owner or admin tool:
 
-// Password login can also include org context
-await sso.auth.login({
-  email: 'user@example.com',
-  password: 'SecurePass123!',
-  org_slug: 'acme-corp',   // Optional: scopes JWT to this org
-  service_slug: 'main-app',
-  redirect_uri: 'https://app.acme.com/callback'
-});
-// JWT contains: { org: 'acme-corp', ... }
+```ts
+const sso = new SsoClient({ baseURL: 'https://sso.example.com' });
 ```
 
-**When to use:** Customer-facing apps, SaaS products, multi-tenant applications.
-
-### Why Context Matters
-
-| Context | JWT Claims | OAuth Credentials Used |
-|---------|-----------|----------------------|
-| Platform-level | `is_platform_owner: true` | Platform's `PLATFORM_*` credentials |
-| Multi-tenant | `org: 'slug'`, `service: 'slug'` | Tenant's BYOO credentials (or platform fallback) |
+### Tenant application
 
-The `org` and `service` parameters ensure:
-- **Identity isolation**: User identities are scoped to specific services
-- **Credential isolation**: Each tenant can use their own OAuth app credentials
-- **Proper attribution**: Login events are tracked per organization/service
+Pass organization and service context when you need hosted auth, BYOO, or service-scoped tokens:
 
-**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.
-
-**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
-// Redirect to OAuth provider
+```ts
 const loginUrl = sso.auth.getLoginUrl('github', {
   org: 'acme-corp',
   service: 'main-app',
-  redirect_uri: 'https://app.acme.com/callback'
-});
-window.location.href = loginUrl;
-
-// Handle callback - tokens are returned in URL fragment (#) for security
-// (prevents tokens from being logged in server access logs)
-const hashParams = new URLSearchParams(window.location.hash.substring(1));
-const accessToken = hashParams.get('access_token');
-
-if (accessToken) {
-  // Clear hash from URL for security
-  window.history.replaceState(null, '', window.location.pathname);
-
-  // Initialize SDK with OAuth token - automatically stored
-  const sso = new SsoClient({
-    baseURL: 'https://sso.example.com',
-    token: accessToken
-  });
-  // Token is now automatically stored and managed
-  window.location.href = '/dashboard';
-}
-```
-
-### Password Authentication
-
-```typescript
-// Register new user (tenant-first: always include org + service for proper attribution)
-await sso.auth.register({
-  email: 'user@example.com',
-  password: 'SecurePass123!',
-  org_slug: 'acme-corp',     // Your organization
-  service_slug: 'main-app'   // Your application
-});
-// User identity is now scoped to your org and service
-
-// Login with password (service-scoped: include org + service)
-await sso.auth.login({
-  email: 'user@example.com',
-  password: 'SecurePass123!',
-  org_slug: 'acme-corp',     // Your organization
-  service_slug: 'main-app'   // Your application
+  redirect_uri: 'https://app.acme.com/callback',
 });
-// JWT is now scoped to org + service
-
-// Enable MFA
-const mfaSetup = await sso.user.mfa.setup();
-console.log(mfaSetup.qr_code_svg); // Display QR code to user
-
-// Verify and enable - automatically saves backup codes
-const result = await sso.user.mfa.verify('123456'); // TOTP code from authenticator app
-console.log('Backup codes:', result.backup_codes); // Save these securely!
 ```
 
-### Hosted Auth Context & Passwordless
+### Hosted auth context
 
-```typescript
+```ts
 const context = await sso.auth.getContext({
   org: 'acme-corp',
   service: 'main-app',
-  redirect_uri: 'https://app.acme.com/callback'
-});
-
-console.log(context.organization?.name);
-console.log(context.available_providers); // ['github', 'google', 'microsoft']
-
-await sso.magicLinks.request({
-  email: 'user@example.com',
-  org_slug: 'acme-corp',
-  service_slug: 'main-app',
-  redirect_uri: 'https://app.acme.com/callback'
-});
-
-const passkeyLogin = await sso.passkeys.login('user@example.com', {
-  org_slug: 'acme-corp',
-  service_slug: 'main-app',
-  redirect_uri: 'https://app.acme.com/callback'
+  redirect_uri: 'https://app.acme.com/callback',
 });
-
-await sso.setSession({
-  access_token: passkeyLogin.access_token,
-  refresh_token: passkeyLogin.refresh_token
-});
-```
-
-### Passkey Self-Service
-
-```typescript
-const passkeys = await sso.passkeys.list();
-
-if (passkeys.length > 0) {
-  await sso.passkeys.updateName(passkeys[0].id, 'Work Laptop');
-  await sso.passkeys.delete(passkeys[0].id);
-}
 ```
 
-### Device Flow (for CLIs)
+### Provider token handoff
 
-```typescript
-// In your CLI application
-const deviceAuth = await sso.auth.deviceCode.request({
-  client_id: 'cli-client',
-  org: 'acme-corp',
-  service: 'cli-tool'
+```ts
+const result = await sso.serviceApi.requestProviderToken({
+  user_id: 'user-id',
+  provider: 'github',
+  scopes: ['repo'],
 });
-
-console.log(`Visit: ${deviceAuth.verification_uri}`);
-console.log(`Enter code: ${deviceAuth.user_code}`);
-
-// Poll for token
-const interval = setInterval(async () => {
-  try {
-    const tokens = await sso.auth.deviceCode.exchangeToken({
-      device_code: deviceAuth.device_code,
-      client_id: 'cli-client',
-      grant_type: 'urn:ietf:params:oauth:grant-type:device_code'
-    });
-
-    // Initialize SDK with the token - automatically stored
-    const authenticatedSso = new SsoClient({
-      baseURL: 'https://sso.example.com',
-      token: tokens.access_token
-    });
-
-    clearInterval(interval);
-    console.log('Authentication successful!');
-  } catch (error) {
-    // Continue polling...
-  }
-}, deviceAuth.interval * 1000);
-```
-
-### Token Refresh
-
-**Automatic Token Refresh** - The SDK automatically refreshes expired tokens when it detects a 401 error:
-
-```typescript
-// No manual refresh needed! Just make your API calls
-try {
-  // If the access token is expired, the SDK will:
-  // 1. Detect the 401 error
-  // 2. Use the refresh token to get new tokens
-  // 3. Retry the request automatically
-  // 4. Return the result - you never see the 401!
-  const profile = await sso.user.getProfile();
-  console.log(profile);
-} catch (error) {
-  // You'll only see errors if refresh fails (e.g., refresh token expired)
-  console.error('Session expired - please log in again');
-  // Redirect to login
-}
-
-// Optional: Manually refresh if needed (advanced use case)
-const currentRefreshToken = await sso.getToken();
-if (currentRefreshToken) {
-  const tokens = await sso.auth.refreshToken(currentRefreshToken);
-  // Tokens automatically updated
-}
 ```
 
-## Organization Management
-
-```typescript
-// Create organization
-const org = await sso.organizations.create({
-  name: 'Acme Corp',
-  slug: 'acme-corp'
-});
-
-// 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'
-});
-
-// Invite team members
-await sso.invitations.create('acme-corp', {
-  email: 'member@acme.com',
-  role: 'admin'
-});
-
-// 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'
-});
-```
-
-## Subscription & Billing
-
-The SDK provides provider-agnostic billing integration that works with both Stripe and Polar.
-
-```typescript
-// Check billing status
-const billingInfo = await sso.organizations.billing.getInfo('acme-corp');
-console.log(billingInfo.has_billing_account); // true/false
-console.log(billingInfo.provider); // "stripe" or "polar"
-
-// Open billing portal for subscription management
-const portal = await sso.organizations.billing.createPortalSession('acme-corp', {
-  return_url: 'https://app.acme.com/settings/billing'
-});
-// Redirect user to manage their subscription
-window.location.href = portal.url;
-```
-
-### BYOP - Bring Your Own Payment
-
-Organizations can configure their own billing provider credentials to charge their end-users:
-
-```typescript
-// Configure organization's own Stripe credentials
-await sso.organizations.billingCredentials.set('acme-corp', 'stripe', {
-  api_key: 'sk_live_...',
-  webhook_secret: 'whsec_...',
-  mode: 'live' // or 'test'
-});
-
-// Check credential status
-const status = await sso.organizations.billingCredentials.get('acme-corp', 'stripe');
-console.log(status.configured); // true
-console.log(status.mode); // "live"
-
-// Remove credentials
-await sso.organizations.billingCredentials.delete('acme-corp', 'stripe');
-```
-
-## Services & API Keys
-
-```typescript
-// Create a service
-const service = await sso.services.create('acme-corp', {
-  name: 'Main Application',
-  slug: 'main-app',
-  redirect_uris: ['https://app.acme.com/callback']
-});
-
-// 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'
-});
-
-console.log('API Key (save this):', apiKey.key);
-
-// Use API key for backend authentication
-const backendClient = new SsoClient({
-  baseURL: 'https://sso.example.com',
-  apiKey: apiKey.key
-});
-
-const rotated = await sso.services.rotateSecret('acme-corp', 'main-app');
-console.log('New client secret:', rotated.client_secret);
-```
-
-## Fine-Grained Member Access
-
-```typescript
-const access = await sso.organizations.members.updateServiceAccess(
-  'acme-corp',
-  'user-id',
-  {
-    grants: [
-      { service_slug: 'main-app', access: 'manager' },
-      { service_slug: 'docs-app', access: 'viewer' }
-    ]
-  }
-);
-
-console.log(access);
-```
-
-## Analytics
-
-```typescript
-// Get login trends
-const trends = await sso.analytics.getLoginTrends('acme-corp', {
-  start_date: '2025-01-01',
-  end_date: '2025-01-31'
-});
-
-// Get provider distribution
-const byProvider = await sso.analytics.getLoginsByProvider('acme-corp');
-console.log(byProvider); // [{ provider: 'github', count: 1523 }, ...]
-
-// Get recent activity
-const recentLogins = await sso.analytics.getRecentLogins('acme-corp', {
-  limit: 20
-});
-```
-
-## Error Handling
-
-```typescript
-import { SsoClient, SsoApiError } from '@drmhse/sso-sdk';
-
-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}`);
-
-    if (error.status === 401) {
-      // Session expired (refresh token also expired)
-      // Automatic refresh already tried and failed
-      // Redirect to login
-      window.location.href = '/login';
-    } else if (error.status === 403) {
-      // Forbidden - insufficient permissions
-      console.error('You do not have permission to access this resource');
-    }
-  } else {
-    console.error('Unexpected error:', error);
-  }
-}
-
-// React to authentication state changes
-sso.onAuthStateChange((isAuthenticated) => {
-  if (!isAuthenticated) {
-    // User logged out or session expired
-    window.location.href = '/login';
-  }
-});
-```
-
-## Platform Administration
-
-For platform owners managing [AuthOS](https://authos.dev):
-
-```typescript
-// Approve pending organization
-await sso.platform.organizations.approve('org-id', {
-  tier: 'professional',
-  reason: 'Verified enterprise customer'
-});
-
-// 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');
-
-// Inspect operational health
-const ops = await sso.platform.getOperationsStatus();
-console.log(ops.jobs_pending, ops.webhook_deliveries_failed);
-```
-
-## TypeScript Support
-
-The SDK is written in TypeScript and includes complete type definitions:
-
-```typescript
-import type {
-  User,
-  Organization,
-  Service,
-  LoginTrendPoint,
-  RefreshTokenResponse,
-  CreateServicePayload,
-  UpdateServicePayload,
-  LoginPayload,
-  RegisterPayload,
-  SsoApiError
-} from '@drmhse/sso-sdk';
-
-// Example using types
-const createService = async (payload: CreateServicePayload): Promise<Service> => {
-  return await sso.services.create('org-slug', payload);
-};
-
-const login = async (credentials: LoginPayload): Promise<RefreshTokenResponse> => {
-  return await sso.auth.login(credentials);
-};
-```
-
-## Validating JWTs in Your Backend
-
-[AuthOS](https://authos.dev) uses RS256 (asymmetric) JWT signing. Your backend can validate tokens without sharing secrets:
-
-```typescript
-// 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();
-
-// Use a JWT library to verify tokens
-import jwt from 'jsonwebtoken';
-import jwksClient from 'jwks-rsa';
-
-const client = jwksClient({ jwksUri: jwksUrl });
-const key = await client.getSigningKey(header.kid);
-const publicKey = key.getPublicKey();
-
-const decoded = jwt.verify(token, publicKey, {
-  algorithms: ['RS256']
-});
-```
-
-**[See Backend Validation Guide →](https://drmhse.com/docs/sso/api/concepts/token-validation)**
-
-## Documentation
-
-**[Complete documentation is available at drmhse.com/docs/sso](https://drmhse.com/docs/sso/)**
-
-### Key Documentation Pages
-
-- **[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
-
-## Requirements
-
-- **Node.js:** 18+ (for native fetch support)
-- **Browsers:** All modern browsers with fetch support
-- **TypeScript:** 4.5+ (optional, but recommended)
-
-## License
+## Feature highlights
 
-MIT © [DRM HSE](https://github.com/drmhse)
+- Password, OAuth, magic-link, passkey, MFA, and device-flow authentication
+- Hosted auth context for login surfaces
+- Linked accounts and provider-token request completion flows
+- Organization, service, analytics, audit-log, and platform-owner APIs
+- Service API helpers including backend-only provider token retrieval
 
-## Support
+## Canonical references
 
-- **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)
+- SDK getting started: [authos.dev/docs/sdk/getting-started/](https://authos.dev/docs/sdk/getting-started/)
+- SDK reference: [authos.dev/docs/sdk/reference/](https://authos.dev/docs/sdk/reference/)
+- API reference: [authos.dev/docs/api/reference/](https://authos.dev/docs/api/reference/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drmhse/sso-sdk",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Zero-dependency TypeScript SDK for AuthOS, the multi-tenant authentication platform",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -44,18 +44,17 @@
   ],
   "author": "DRM HSE <info@drmhse.com>",
   "license": "MIT",
-  "dependencies": {},
   "devDependencies": {
     "@types/node": "^20.11.5",
-    "@typescript-eslint/eslint-plugin": "^6.19.0",
-    "@typescript-eslint/parser": "^6.19.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.4",
+    "@typescript-eslint/parser": "^8.59.4",
     "eslint": "^8.56.0",
     "tsup": "^8.0.1",
     "typescript": "^5.3.3"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/drmhse/sso.git",
+    "url": "https://github.com/drmhse/AuthOS.git",
     "directory": "sso-sdk"
   },
   "publishConfig": {