@harperfast/oauth 1.2.1

package/dist/lib/sessionValidator.d.ts

@@ -0,0 +1,38 @@
+/**
+ * OAuth Session Validation and Token Refresh
+ *
+ * Handles automatic validation and refresh of OAuth tokens in sessions
+ */
+import type { Request, IOAuthProvider, Logger } from '../types.ts';
+import type { HookManager } from './hookManager.ts';
+export interface SessionValidationResult {
+    /** Whether the session has valid OAuth data */
+    valid: boolean;
+    /** Whether tokens were refreshed during validation */
+    refreshed?: boolean;
+    /** Error message if validation failed */
+    error?: string;
+}
+/**
+ * Validate OAuth session and refresh tokens if needed
+ *
+ * This function checks if OAuth tokens in the session are expired or approaching
+ * expiration, and automatically refreshes them if possible.
+ *
+ * Token refresh strategy:
+ * - If token is expired (past expiresAt), refresh immediately
+ * - If token is approaching expiration (past refreshThreshold = 80% of lifetime), refresh proactively
+ * - If no refresh token available and token is expired, clear OAuth session data
+ *
+ * @param request - Harper request object with session
+ * @param provider - OAuth provider instance for token refresh
+ * @param logger - Optional logger for debugging
+ * @param hookManager - Optional hook manager for calling onTokenRefresh hook
+ * @returns Validation result indicating if session is valid and if refresh occurred
+ */
+export declare function validateAndRefreshSession(request: Request, provider: IOAuthProvider, logger?: Logger, hookManager?: HookManager): Promise<SessionValidationResult>;
+/**
+ * Check if a session has valid OAuth authentication
+ * Does not refresh tokens, only checks validity
+ */
+export declare function hasValidOAuthSession(request: Request): boolean;

package/dist/lib/sessionValidator.js

@@ -0,0 +1,162 @@
+/**
+ * OAuth Session Validation and Token Refresh
+ *
+ * Handles automatic validation and refresh of OAuth tokens in sessions
+ */
+import { clearOAuthSession } from "./handlers.js";
+/**
+ * Validate OAuth session and refresh tokens if needed
+ *
+ * This function checks if OAuth tokens in the session are expired or approaching
+ * expiration, and automatically refreshes them if possible.
+ *
+ * Token refresh strategy:
+ * - If token is expired (past expiresAt), refresh immediately
+ * - If token is approaching expiration (past refreshThreshold = 80% of lifetime), refresh proactively
+ * - If no refresh token available and token is expired, clear OAuth session data
+ *
+ * @param request - Harper request object with session
+ * @param provider - OAuth provider instance for token refresh
+ * @param logger - Optional logger for debugging
+ * @param hookManager - Optional hook manager for calling onTokenRefresh hook
+ * @returns Validation result indicating if session is valid and if refresh occurred
+ */
+export async function validateAndRefreshSession(request, provider, logger, hookManager) {
+    const session = request.session;
+    // No session available
+    if (!session) {
+        return { valid: false, error: 'No session available' };
+    }
+    // Check for OAuth metadata in session
+    const oauthMetadata = session.oauth;
+    if (!oauthMetadata) {
+        // No OAuth data in session - not an OAuth session
+        return { valid: false, error: 'No OAuth data in session' };
+    }
+    // Validate required fields
+    if (!oauthMetadata.accessToken) {
+        logger?.warn?.('OAuth session missing access token, logging out');
+        await clearOAuthSession(session, logger);
+        return { valid: false, error: 'OAuth session missing access token' };
+    }
+    const now = Date.now();
+    const isExpired = oauthMetadata.expiresAt ? now >= oauthMetadata.expiresAt : false;
+    const needsRefresh = oauthMetadata.refreshThreshold ? now >= oauthMetadata.refreshThreshold : false;
+    // For tokens without expiration (like GitHub), perform periodic validation
+    if (!oauthMetadata.expiresAt && !oauthMetadata.refreshThreshold && provider.config.validateToken) {
+        const validationInterval = provider.config.tokenValidationInterval || 15 * 60 * 1000; // Default 15 minutes
+        const lastCheck = oauthMetadata.lastValidated || oauthMetadata.lastRefreshed || 0;
+        const timeSinceLastCheck = now - lastCheck;
+        if (timeSinceLastCheck > validationInterval) {
+            logger?.debug?.('Performing periodic token validation for non-expiring token');
+            try {
+                const isValid = await provider.config.validateToken(oauthMetadata.accessToken, logger);
+                if (!isValid) {
+                    logger?.debug?.('OAuth token validation failed (token revoked or invalid), logging out');
+                    await clearOAuthSession(session, logger);
+                    return { valid: false, error: 'Token validation failed - token may have been revoked' };
+                }
+                // Update last validated timestamp in session
+                oauthMetadata.lastValidated = now;
+                session.oauth = oauthMetadata;
+                if (typeof session.update === 'function') {
+                    await session.update(session);
+                }
+                logger?.debug?.('Token validation successful');
+            }
+            catch (error) {
+                logger?.error?.('Token validation error:', error.message);
+                // Don't logout on validation errors - could be network issue
+                // Token will be validated again on next request
+            }
+        }
+        return { valid: true, refreshed: false };
+    }
+    // Token is still valid and doesn't need refresh
+    if (!isExpired && !needsRefresh) {
+        return { valid: true, refreshed: false };
+    }
+    // Token needs refresh - check if refresh token is available
+    if (!oauthMetadata.refreshToken) {
+        if (isExpired) {
+            logger?.warn?.('OAuth token expired and no refresh token available, logging out');
+            await clearOAuthSession(session, logger);
+            return { valid: false, error: 'Token expired and no refresh token available' };
+        }
+        // Token approaching expiration but no refresh token - still valid for now
+        return { valid: true, refreshed: false };
+    }
+    // Attempt to refresh the token
+    logger?.debug?.(isExpired
+        ? 'OAuth token expired, attempting refresh...'
+        : 'OAuth token approaching expiration (80% lifetime), refreshing proactively...');
+    try {
+        // Check if provider supports token refresh
+        if (!provider.refreshAccessToken) {
+            logger?.warn?.('OAuth provider does not support token refresh');
+            if (isExpired) {
+                await clearOAuthSession(session, logger);
+                return { valid: false, error: 'Token expired and provider does not support refresh' };
+            }
+            return { valid: true, refreshed: false };
+        }
+        // Attempt to refresh the token
+        logger?.debug?.('Attempting token refresh with refresh token');
+        // Perform token refresh
+        const tokenResponse = await provider.refreshAccessToken(oauthMetadata.refreshToken);
+        // Calculate new expiration times
+        const expiresIn = tokenResponse.expires_in || 3600; // Default 1 hour
+        const newExpiresAt = now + expiresIn * 1000;
+        const newRefreshThreshold = now + expiresIn * 800; // Refresh at 80% of lifetime
+        // Update session with new tokens and metadata
+        const updatedMetadata = {
+            provider: oauthMetadata.provider,
+            providerConfigId: oauthMetadata.providerConfigId,
+            providerType: oauthMetadata.providerType,
+            accessToken: tokenResponse.access_token,
+            refreshToken: tokenResponse.refresh_token || oauthMetadata.refreshToken, // Keep existing if not provided
+            expiresAt: newExpiresAt,
+            refreshThreshold: newRefreshThreshold,
+            scope: tokenResponse.scope || oauthMetadata.scope,
+            tokenType: tokenResponse.token_type || oauthMetadata.tokenType,
+            lastRefreshed: now,
+            lastValidated: oauthMetadata.lastValidated, // Preserve if exists
+        };
+        // Update session with refreshed token
+        session.oauth = updatedMetadata;
+        if (typeof session.update === 'function') {
+            await session.update(session);
+        }
+        logger?.info?.('OAuth token refreshed successfully');
+        // Call onTokenRefresh hook
+        if (hookManager) {
+            await hookManager.callOnTokenRefresh(session, true, request);
+        }
+        return { valid: true, refreshed: true };
+    }
+    catch (error) {
+        logger?.error?.('OAuth token refresh failed:', error.message);
+        // If token was expired and refresh failed, log out
+        if (isExpired) {
+            await clearOAuthSession(session, logger);
+            return { valid: false, error: `Token refresh failed: ${error.message}` };
+        }
+        // Token not yet expired, allow continued use
+        return { valid: true, refreshed: false };
+    }
+}
+/**
+ * Check if a session has valid OAuth authentication
+ * Does not refresh tokens, only checks validity
+ */
+export function hasValidOAuthSession(request) {
+    const session = request.session;
+    if (!session)
+        return false;
+    const oauthMetadata = session.oauth;
+    if (!oauthMetadata || !oauthMetadata.accessToken)
+        return false;
+    // Check if token is expired - return true if valid, false if expired
+    return !(oauthMetadata.expiresAt && Date.now() >= oauthMetadata.expiresAt);
+}
+//# sourceMappingURL=sessionValidator.js.map

package/dist/lib/sessionValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionValidator.js","sourceRoot":"","sources":["../../src/lib/sessionValidator.ts"],"names":[],"mappings":"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"}

package/dist/lib/tenantManager.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Multi-Tenant SSO Manager
+ *
+ * Enables dynamic tenant routing for enterprise SSO
+ * Supports Okta, Azure AD, Auth0, and any domain-based OAuth provider
+ */
+import type { OAuthProviderConfig, Logger } from '../types.ts';
+export interface TenantConfig {
+    /** Unique tenant identifier (e.g., 'acme-corp', 'globex') */
+    tenantId: string;
+    /** Tenant display name */
+    name: string;
+    /** OAuth provider type (okta, azure, auth0, etc.) */
+    provider: 'okta' | 'azure' | 'auth0' | string;
+    /** Provider-specific domain (for Okta/Auth0) or tenant ID (for Azure) */
+    domain?: string;
+    /** Azure AD specific tenant ID (alternative to domain) */
+    azureTenantId?: string;
+    /** OAuth client ID for this tenant */
+    clientId: string;
+    /** OAuth client secret for this tenant */
+    clientSecret: string;
+    /** Optional: Email domains that belong to this tenant */
+    emailDomains?: string[];
+    /** Optional: Custom scopes */
+    scope?: string;
+    /** Optional: Custom post-login redirect */
+    postLoginRedirect?: string;
+    /** Optional: Additional provider-specific config */
+    additionalConfig?: Record<string, any>;
+}
+export interface TenantRegistryEntry {
+    config: TenantConfig;
+    providerConfig: OAuthProviderConfig;
+}
+export declare class TenantManager {
+    private tenants;
+    private domainToTenant;
+    private logger?;
+    constructor(logger?: Logger);
+    /**
+     * Register a tenant with their OAuth provider configuration
+     * Supports Okta, Azure AD, Auth0, and custom providers
+     */
+    registerTenant(tenant: TenantConfig): void;
+    /**
+     * Register multiple tenants at once
+     */
+    registerTenants(tenants: TenantConfig[]): void;
+    /**
+     * Get tenant by ID
+     *
+     * ⚠️ **Security Warning**: Returns full tenant configuration including clientSecret.
+     * This method is intended for internal use (hooks, OAuth flows) only.
+     * Never expose the returned TenantRegistryEntry directly in HTTP responses.
+     *
+     * @example
+     * // ✅ Safe: Use in hooks/internal logic
+     * const tenant = tenantManager.getTenant(provider);
+     * return { tenantName: tenant?.config.name };
+     *
+     * // ❌ Unsafe: Direct HTTP exposure
+     * return { tenant: tenantManager.getTenant(id) }; // Leaks clientSecret!
+     */
+    getTenant(tenantId: string): TenantRegistryEntry | undefined;
+    /**
+     * Get tenant by email domain
+     *
+     * ⚠️ **Security Warning**: Returns full tenant configuration including clientSecret.
+     * This method is intended for internal use (hooks, OAuth flows) only.
+     * Never expose the returned TenantRegistryEntry directly in HTTP responses.
+     */
+    getTenantByEmail(email: string): TenantRegistryEntry | undefined;
+    /**
+     * Get all registered tenants
+     *
+     * Note: clientSecret is automatically redacted for security.
+     * Secrets are only needed internally for OAuth flows.
+     */
+    getAllTenants(): TenantConfig[];
+    /**
+     * Convert tenant configurations to provider registry format
+     * This can be merged with the standard provider registry
+     *
+     * ⚠️ **Security Warning**: Returns provider configurations including clientSecret.
+     * This method is intended for OAuth plugin initialization only.
+     * The returned configs are needed for OAuth token exchange flows.
+     * Never expose these configurations in HTTP responses.
+     */
+    toProviderRegistry(): Record<string, {
+        provider: any;
+        config: OAuthProviderConfig;
+    }>;
+    /**
+     * Load tenants from configuration
+     * Supports both static config and dynamic loading from database
+     */
+    static fromConfig(config: {
+        tenants?: TenantConfig[];
+        logger?: Logger;
+    }): TenantManager;
+}

package/dist/lib/tenantManager.js

@@ -0,0 +1,177 @@
+/**
+ * Multi-Tenant SSO Manager
+ *
+ * Enables dynamic tenant routing for enterprise SSO
+ * Supports Okta, Azure AD, Auth0, and any domain-based OAuth provider
+ */
+import { getProvider } from "./providers/index.js";
+import { validateTenantId, validateEmailDomain } from "./providers/validation.js";
+export class TenantManager {
+    tenants = new Map();
+    domainToTenant = new Map();
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Register a tenant with their OAuth provider configuration
+     * Supports Okta, Azure AD, Auth0, and custom providers
+     */
+    registerTenant(tenant) {
+        // Validate tenant ID format
+        validateTenantId(tenant.tenantId);
+        // Validate email domains
+        if (tenant.emailDomains) {
+            for (const domain of tenant.emailDomains) {
+                validateEmailDomain(domain);
+            }
+        }
+        // Get the base provider configuration
+        const baseProvider = getProvider(tenant.provider);
+        if (!baseProvider) {
+            throw new Error(`Unknown provider type: ${tenant.provider}`);
+        }
+        // Apply provider-specific configuration
+        // Note: Provider configure() methods now include security validation
+        let providerSpecificConfig = {};
+        if (baseProvider.configure) {
+            switch (tenant.provider) {
+                case 'okta':
+                case 'auth0':
+                    if (!tenant.domain) {
+                        throw new Error(`${tenant.provider} provider requires domain configuration`);
+                    }
+                    providerSpecificConfig = baseProvider.configure(tenant.domain);
+                    break;
+                case 'azure':
+                case 'microsoft':
+                    if (!tenant.azureTenantId) {
+                        throw new Error('Azure AD provider requires azureTenantId configuration');
+                    }
+                    providerSpecificConfig = baseProvider.configure(tenant.azureTenantId);
+                    break;
+                default:
+                    // For custom providers, pass domain or azureTenantId if available
+                    const configParam = tenant.domain || tenant.azureTenantId;
+                    if (configParam) {
+                        providerSpecificConfig = baseProvider.configure(configParam);
+                    }
+            }
+        }
+        // Build the complete provider configuration
+        const providerConfig = {
+            ...baseProvider,
+            ...providerSpecificConfig,
+            provider: tenant.provider,
+            clientId: tenant.clientId,
+            clientSecret: tenant.clientSecret,
+            scope: tenant.scope || baseProvider.scope,
+            postLoginRedirect: tenant.postLoginRedirect,
+            ...tenant.additionalConfig,
+        };
+        this.tenants.set(tenant.tenantId, {
+            config: tenant,
+            providerConfig,
+        });
+        // Map email domains to tenant (already validated above)
+        if (tenant.emailDomains) {
+            for (const domain of tenant.emailDomains) {
+                const normalizedDomain = domain.toLowerCase();
+                const existingTenantId = this.domainToTenant.get(normalizedDomain);
+                if (existingTenantId && existingTenantId !== tenant.tenantId) {
+                    this.logger?.warn?.(`Email domain "${normalizedDomain}" is already mapped to tenant "${existingTenantId}". ` +
+                        `Overwriting with tenant "${tenant.tenantId}".`);
+                }
+                this.domainToTenant.set(normalizedDomain, tenant.tenantId);
+            }
+        }
+        this.logger?.info?.(`Registered tenant: ${tenant.name} (${tenant.tenantId}) using ${tenant.provider} provider`);
+    }
+    /**
+     * Register multiple tenants at once
+     */
+    registerTenants(tenants) {
+        for (const tenant of tenants) {
+            this.registerTenant(tenant);
+        }
+    }
+    /**
+     * Get tenant by ID
+     *
+     * ⚠️ **Security Warning**: Returns full tenant configuration including clientSecret.
+     * This method is intended for internal use (hooks, OAuth flows) only.
+     * Never expose the returned TenantRegistryEntry directly in HTTP responses.
+     *
+     * @example
+     * // ✅ Safe: Use in hooks/internal logic
+     * const tenant = tenantManager.getTenant(provider);
+     * return { tenantName: tenant?.config.name };
+     *
+     * // ❌ Unsafe: Direct HTTP exposure
+     * return { tenant: tenantManager.getTenant(id) }; // Leaks clientSecret!
+     */
+    getTenant(tenantId) {
+        return this.tenants.get(tenantId);
+    }
+    /**
+     * Get tenant by email domain
+     *
+     * ⚠️ **Security Warning**: Returns full tenant configuration including clientSecret.
+     * This method is intended for internal use (hooks, OAuth flows) only.
+     * Never expose the returned TenantRegistryEntry directly in HTTP responses.
+     */
+    getTenantByEmail(email) {
+        const domain = email.split('@')[1]?.toLowerCase();
+        if (!domain)
+            return undefined;
+        const tenantId = this.domainToTenant.get(domain);
+        if (!tenantId)
+            return undefined;
+        return this.tenants.get(tenantId);
+    }
+    /**
+     * Get all registered tenants
+     *
+     * Note: clientSecret is automatically redacted for security.
+     * Secrets are only needed internally for OAuth flows.
+     */
+    getAllTenants() {
+        return Array.from(this.tenants.values()).map((entry) => ({
+            ...entry.config,
+            clientSecret: undefined, // Redact secret for security
+        }));
+    }
+    /**
+     * Convert tenant configurations to provider registry format
+     * This can be merged with the standard provider registry
+     *
+     * ⚠️ **Security Warning**: Returns provider configurations including clientSecret.
+     * This method is intended for OAuth plugin initialization only.
+     * The returned configs are needed for OAuth token exchange flows.
+     * Never expose these configurations in HTTP responses.
+     */
+    toProviderRegistry() {
+        const registry = {};
+        for (const [tenantId, entry] of this.tenants) {
+            // We'll need to create a provider instance here
+            // For now, return the config - the caller will need to instantiate OAuthProvider
+            registry[tenantId] = {
+                provider: null, // Will be instantiated by caller
+                config: entry.providerConfig,
+            };
+        }
+        return registry;
+    }
+    /**
+     * Load tenants from configuration
+     * Supports both static config and dynamic loading from database
+     */
+    static fromConfig(config) {
+        const manager = new TenantManager(config.logger);
+        if (config.tenants) {
+            manager.registerTenants(config.tenants);
+        }
+        return manager;
+    }
+}
+//# sourceMappingURL=tenantManager.js.map

package/dist/lib/tenantManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenantManager.js","sourceRoot":"","sources":["../../src/lib/tenantManager.ts"],"names":[],"mappings":"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"}

package/dist/lib/withOAuthValidation.d.ts

@@ -0,0 +1,64 @@
+/**
+ * OAuth Session Validation Wrapper
+ *
+ * Wraps Harper resources to add automatic OAuth session validation and token refresh
+ * before handling any request. This enables transparent token management for protected endpoints.
+ */
+import type { Request, Logger, ProviderRegistry } from '../types.ts';
+export interface OAuthValidationOptions {
+    /** OAuth provider registry from plugin initialization */
+    providers: ProviderRegistry;
+    /** Logger instance for debugging */
+    logger?: Logger;
+    /** Whether to require OAuth authentication (401 if not present) */
+    requireAuth?: boolean;
+    /** Custom error handler for validation failures */
+    onValidationError?: (request: Request, error: string) => any;
+}
+/**
+ * Wraps a Harper resource to add automatic OAuth session validation
+ *
+ * This wrapper intercepts all resource method calls (get, post, put, patch, delete)
+ * and validates/refreshes OAuth tokens before passing the request to the original resource.
+ *
+ * @example
+ * ```typescript
+ * // In your application component:
+ * import { withOAuthValidation } from '@harperfast/oauth';
+ *
+ * export function handleApplication(scope) {
+ *   // Get OAuth providers from the OAuth plugin
+ *   const oauthPlugin = scope.parent.resources.get('oauth');
+ *
+ *   // Wrap your protected resource
+ *   const myResource = {
+ *     async get(target, request) {
+ *       // This code only runs if OAuth session is valid
+ *       return { user: request.session.oauthUser };
+ *     }
+ *   };
+ *
+ *   scope.resources.set('protected', withOAuthValidation(myResource, {
+ *     providers: oauthPlugin.providers,
+ *     requireAuth: true,
+ *     logger: scope.logger
+ *   }));
+ * }
+ * ```
+ */
+export declare function withOAuthValidation(resource: any, options: OAuthValidationOptions): any;
+/**
+ * Helper to get OAuth providers from the OAuth plugin
+ * Call this from your application to access the provider registry
+ *
+ * @example
+ * ```typescript
+ * import { getOAuthProviders } from '@harperfast/oauth';
+ *
+ * export function handleApplication(scope) {
+ *   const providers = getOAuthProviders(scope);
+ *   // Use providers with withOAuthValidation
+ * }
+ * ```
+ */
+export declare function getOAuthProviders(scope: any): ProviderRegistry | null;