SSO SDK for TypeScript

A robust, type-safe TypeScript SDK for integrating with the SSO service. Designed for backend applications (Node.js, Bun, Deno) with framework-agnostic token management.

Features

• Secure by Default: Automatic token refresh and secure defaults.
• Storage Agnostic: In-memory token management with hooks for any storage backend (Session, Redis, DB).
• Framework Independent: Works with Express, Fastify, Hono, NestJS, and more.
• Type-Safe: Full TypeScript support with comprehensive types.

Installation

npm install @rshelekhov/sso-sdk
# or
bun add @rshelekhov/sso-sdk

Quick Start

1. Initialize the Client

import { SSOClient, Platform } from '@rshelekhov/sso-sdk';

const ssoClient = new SSOClient({
  baseUrl: 'https://api.sso-service.com',
  clientId: 'your-client-id',
  publicUrls: {
    emailVerification: 'https://yourapp.com/verify-email',
    passwordReset: 'https://yourapp.com/reset-password'
  }
});

2. Login and Store Tokens

// In your login route handler
const deviceContext = {
  platform: Platform.WEB,
  clientIP: req.ip,
  userAgent: req.headers['user-agent']
};

const tokens = await ssoClient.login('[email protected]', 'password', deviceContext);

// Store tokens in your session (implementation depends on your framework)
req.session.tokens = tokens;

3. Protect Routes

// In your protected route middleware
const tokens = req.session.tokens;

if (!tokens) {
  return res.status(401).send('Unauthorized');
}

// Load tokens into SDK
ssoClient.setTokens(tokens);

try {
  // This will automatically refresh the token if needed
  const user = await ssoClient.getProfile(deviceContext);
  
  // Check if tokens were refreshed and save them if so
  const newTokens = ssoClient.getTokens();
  if (newTokens) {
    req.session.tokens = newTokens;
  }
  
  res.json(user);
} catch (error) {
  res.status(401).send('Session expired');
}

JWT Middleware

For stateless authentication, the SDK provides JWT middleware that validates tokens using JWKS:

import { AuthMiddleware } from '@rshelekhov/sso-sdk';

const authMiddleware = new AuthMiddleware({
  jwksUrl: 'https://api.sso-service.com/v1/auth/.well-known/jwks.json',
  issuer: 'sso-service',
  audience: 'your-client-id',
  clientId: 'your-client-id',
});

// Use with your framework
app.use('/api/protected', authMiddleware.hono());  // Hono
app.use('/api/protected', authMiddleware.express());  // Express
fastify.addHook('preHandler', authMiddleware.fastify());  // Fastify

The middleware verifies JWT signatures, validates claims, and attaches user data to the request context. Perfect for microservices and stateless architectures.

Token Storage

The SDK manages tokens in-memory to give you full control over persistence. You are responsible for:

1. Saving tokens to your storage (Session, Redis, etc.) after login or refresh.
2. Loading tokens into the SDK before making authenticated requests.

👉 Read the Token Storage Guide for detailed patterns and examples.

Documentation

• JWT Middleware Guide - Stateless authentication with JWKS
• Token Storage Patterns
• Testing Guide - How to run and write tests
• Security Guide (Coming Soon)
• API Reference (Coming Soon)

Examples

• Hono

Development

Prerequisites

• Bun v1.0+
• Docker (for integration tests)

Setup

# Clone the repository
git clone https://github.com/rshelekhov/sso-sdk-ts.git
cd sso-sdk-ts

# Install dependencies
make install

# Build the SDK
make build

Testing

# Run all tests (starts server, runs tests, stops server)
make test

# Run only unit tests (fast, no server needed)
make test-unit

# Run only integration tests (requires SSO server)
make test-up           # Start SSO server
make test-integration  # Run integration tests
make test-down         # Stop SSO server

# View server logs
make test-logs

# Show all available commands
make help

For detailed testing instructions, see tests/README.md.

Code Quality

# Type checking
make typecheck

# Format code
make format