@drmhse/sso-sdk 0.2.1 → 0.2.3

package/README.md

@@ -4,12 +4,12 @@ A zero-dependency, strongly-typed TypeScript SDK for interacting with the multi-
 
 ## 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 - 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.
 
 ## Installation
 
@@ -97,7 +97,7 @@ const deviceAuth = await sso.auth.deviceCode.request({
 console.log(`Visit: ${deviceAuth.verification_uri}`);
 console.log(`Enter code: ${deviceAuth.user_code}`);
 
-// 3. Poll for the token
+// 4. Poll for the token
 const pollForToken = async () => {
   // Polling logic...
 };
@@ -109,11 +109,12 @@ pollForToken();
 // 2. After user enters the code, verify it to get context
 const context = await sso.auth.deviceCode.verify(userEnteredCode);
 
-// Redirect user to the appropriate login flow with the user_code
+// 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,
+  user_code: userEnteredCode, // CRITICAL: Pass user_code here
 });
 window.location.href = loginUrl; // User logs in, authorizing the device
 ```
@@ -145,11 +146,127 @@ 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'
+});
+
+// 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);
+  });
+}
+
+// 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;
+  }
+});
+
+// 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}` });
+});
+```
+
+### Manual Validation (Node.js)
+
+If you prefer to validate manually without middleware:
+
+```typescript
+import jwt from 'jsonwebtoken';
+import jwksRsa from 'jwks-rsa';
+
+const jwksClient = jwksRsa({
+  jwksUri: 'https://sso.example.com/.well-known/jwks.json'
+});
+
+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();
+
+    // Verify and decode the token
+    const verified = jwt.verify(token, publicKey, {
+      algorithms: ['RS256']
+    });
+
+    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);
+```
+
+### 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
+### Analytics (`sso.analytics`)
 
-The analytics module provides login tracking and metrics for organizations.
+Provides login tracking and metrics for a specific organization.
 
 ```typescript
 // Get login trends over time
@@ -159,7 +276,19 @@ const trends = await sso.analytics.getLoginTrends('acme-corp', {
 });
 ```
 
-### Organizations
+### 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`)
+
+Manages organizations, members, and BYOO credentials.
 
 ```typescript
 // Create organization (public endpoint)
@@ -176,7 +305,7 @@ await sso.organizations.oauthCredentials.set('acme-corp', 'github', {
 });
 ```
 
-### End-User Management
+#### End-User Management (`sso.organizations.endUsers`)
 
 Manage your organization's customers (end-users with subscriptions).
 
@@ -191,7 +320,9 @@ const endUsers = await sso.organizations.endUsers.list('acme-corp', {
 await sso.organizations.endUsers.revokeSessions('acme-corp', 'user-id-123');
 ```
 
-### Services & Plans
+### Services & Plans (`sso.services`)
+
+Manages the applications (services) and subscription plans for an organization.
 
 ```typescript
 // Create a service
@@ -211,9 +342,9 @@ await sso.services.plans.create('acme-corp', 'main-app', {
 });
 ```
 
-### User Profile & Identities
+### User Profile & Identities (`sso.user`)
 
-Manage the authenticated user's own profile and linked social accounts.
+Manages the authenticated user's own profile and linked social accounts.
 
 ```typescript
 // Get profile
@@ -227,7 +358,22 @@ window.location.href = authorization_url;
 await sso.user.identities.unlink('github');
 ```
 
-### Platform Administration
+### Invitations (`sso.invitations`)
+
+Manages team invitations for an organization.
+
+```typescript
+// Create and send an invitation
+await sso.invitations.create('acme-corp', {
+  email: 'new-dev@example.com',
+  role: 'member'
+});
+
+// List invitations for the current user
+const myInvites = await sso.invitations.listForUser();
+```
+
+### Platform Administration (`sso.platform`)
 
 Platform owner methods require a Platform Owner JWT.
 
@@ -241,8 +387,14 @@ const pendingOrgs = await sso.platform.organizations.list({
 await sso.platform.organizations.approve('org-id-123', {
   tier_id: 'tier-starter'
 });
+```
 
-// Get platform-wide analytics
+#### Platform Analytics (`sso.platform.analytics`)
+
+Provides platform-wide metrics for platform owners.
+
+```typescript
+// Get platform-wide analytics overview
 const overview = await sso.platform.analytics.getOverview();
 console.log(`Total Users: ${overview.total_users}`);
 ```

package/dist/index.d.mts

@@ -560,7 +560,6 @@ interface Invitation {
     status: InvitationStatus;
     expires_at: string;
     created_at: string;
-    updated_at: string;
 }
 /**
  * Create invitation payload

package/dist/index.d.ts

@@ -560,7 +560,6 @@ interface Invitation {
     status: InvitationStatus;
     expires_at: string;
     created_at: string;
-    updated_at: string;
 }
 /**
  * Create invitation payload

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drmhse/sso-sdk",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Zero-dependency TypeScript SDK for the multi-tenant SSO Platform API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",