@dainprotocol/oauth2-token-manager 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -24,138 +24,61 @@ interface OAuth2Token {
     createdAt?: number;
     raw?: Record<string, any>;
 }
-interface User {
-    id: string;
-    systemId: string;
-    metadata?: Record<string, any>;
-    createdAt: Date;
-    updatedAt: Date;
-}
-interface UserToken {
-    id: string;
-    userId: string;
-    systemId: string;
-    scopeId: string;
-    provider: string;
-    email?: string;
-    token: OAuth2Token;
-    createdAt: Date;
-    updatedAt: Date;
-}
-interface System {
-    id: string;
-    name: string;
-    description?: string;
-    scopes: Scope[];
-    metadata?: Record<string, any>;
-    createdAt: Date;
-    updatedAt: Date;
-}
-interface Scope {
-    id: string;
-    systemId: string;
-    name: string;
-    type: 'authentication' | 'access' | 'custom';
-    permissions: string[];
-    isolated: boolean;
-    metadata?: Record<string, any>;
-}
 interface AuthorizationState {
     state: string;
     codeVerifier?: string;
     config: OAuth2Config;
-    timestamp: Date;
+    createdAt: Date;
     metadata?: Record<string, any>;
 }
 
-interface CreateUserInput {
-    systemId: string;
-    metadata?: Record<string, any>;
-    email?: string;
-    externalId?: string;
+/**
+ * Simplified storage adapter interface
+ * Only stores tokens with provider, userId, and email as key fields
+ * Enforces uniqueness on provider + email combination
+ */
+interface StorageAdapter {
+    saveToken(input: SaveTokenInput): Promise<StoredToken>;
+    getToken(provider: string, email: string): Promise<StoredToken | null>;
+    getTokenById(id: string): Promise<StoredToken | null>;
+    getTokensByUserId(userId: string): Promise<StoredToken[]>;
+    getTokensByEmail(email: string): Promise<StoredToken[]>;
+    getTokensByProvider(provider: string): Promise<StoredToken[]>;
+    updateToken(id: string, update: UpdateTokenInput): Promise<StoredToken | null>;
+    deleteToken(id: string): Promise<boolean>;
+    deleteTokenByProviderEmail(provider: string, email: string): Promise<boolean>;
+    deleteExpiredTokens(): Promise<number>;
+    saveAuthorizationState(state: Omit<AuthorizationState, 'createdAt'>): Promise<AuthorizationState>;
+    getAuthorizationState(state: string): Promise<AuthorizationState | null>;
+    deleteAuthorizationState(state: string): Promise<boolean>;
+    cleanupExpiredStates(): Promise<number>;
 }
-interface UserTokenWithProfile {
+interface StoredToken {
     id: string;
-    userId: string;
-    systemId: string;
-    scopeId: string;
     provider: string;
-    token: {
-        accessToken: string;
-        refreshToken?: string;
-        expiresAt: Date;
-        expiresIn?: number;
-        tokenType: string;
-        scope?: string;
-        createdAt?: number;
-        raw?: Record<string, any>;
-    };
+    userId: string;
+    email: string;
+    token: OAuth2Token;
+    metadata?: Record<string, any>;
     createdAt: Date;
     updatedAt: Date;
-    user: {
-        email?: string;
-        name?: string;
-        externalId?: string;
-        metadata?: Record<string, any>;
-    };
+}
+interface SaveTokenInput {
+    provider: string;
+    userId: string;
+    email: string;
+    token: OAuth2Token;
+    metadata?: Record<string, any>;
+}
+interface UpdateTokenInput {
+    token?: OAuth2Token;
+    metadata?: Record<string, any>;
 }
 interface ProfileBasedTokenOptions {
     checkProfileEmail?: boolean;
     replaceConflictingTokens?: boolean;
     mergeUserData?: boolean;
 }
-interface StorageAdapter {
-    createSystem(system: Omit<System, 'id' | 'createdAt' | 'updatedAt'>): Promise<System>;
-    getSystem(id: string): Promise<System | null>;
-    updateSystem(id: string, system: Partial<System>): Promise<System>;
-    deleteSystem(id: string): Promise<void>;
-    listSystems(): Promise<System[]>;
-    createScope(scope: Omit<Scope, 'id'>): Promise<Scope>;
-    getScope(id: string): Promise<Scope | null>;
-    getScopesBySystem(systemId: string): Promise<Scope[]>;
-    updateScope(id: string, scope: Partial<Scope>): Promise<Scope>;
-    deleteScope(id: string): Promise<void>;
-    createUser(user: Omit<User, 'id' | 'createdAt' | 'updatedAt'>): Promise<User>;
-    getOrCreateUser(input: CreateUserInput): Promise<User>;
-    findUserByEmail(systemId: string, email: string): Promise<User | null>;
-    findUserByExternalId(systemId: string, externalId: string): Promise<User | null>;
-    getUser(id: string): Promise<User | null>;
-    getUsersBySystem(systemId: string): Promise<User[]>;
-    updateUser(id: string, user: Partial<User>): Promise<User>;
-    deleteUser(id: string): Promise<void>;
-    saveToken(token: Omit<UserToken, 'id' | 'createdAt' | 'updatedAt'>): Promise<UserToken>;
-    saveTokenWithEmailValidation(userId: string, systemId: string, scopeId: string, provider: string, email: string, token: Omit<UserToken, 'id' | 'createdAt' | 'updatedAt'>): Promise<UserToken>;
-    getTokensByUser(userId: string): Promise<UserToken[]>;
-    getTokensByUserAndScope(userId: string, scopeId: string): Promise<UserToken[]>;
-    getTokensByUserAndProvider(userId: string, provider: string): Promise<UserToken[]>;
-    getTokensByUserScopeProvider(userId: string, scopeId: string, provider: string): Promise<UserToken[]>;
-    getTokensByScope(systemId: string, scopeId: string): Promise<UserToken[]>;
-    getTokensByProvider(systemId: string, provider: string): Promise<UserToken[]>;
-    getTokensBySystem(systemId: string): Promise<UserToken[]>;
-    findTokensByEmail(email: string, systemId: string): Promise<UserToken[]>;
-    findTokensByEmailAndScope(email: string, systemId: string, scopeId: string): Promise<UserToken[]>;
-    findTokensByEmailAndProvider(email: string, systemId: string, provider: string): Promise<UserToken[]>;
-    findTokenByEmailScopeProvider(email: string, systemId: string, scopeId: string, provider: string): Promise<UserToken | null>;
-    getTokensByUserWithProfile(userId: string): Promise<UserTokenWithProfile[]>;
-    getTokensByUserAndScopeWithProfile(userId: string, scopeId: string): Promise<UserTokenWithProfile[]>;
-    getTokensByUserAndProviderWithProfile(userId: string, provider: string): Promise<UserTokenWithProfile[]>;
-    getTokensByUserScopeProviderWithProfile(userId: string, scopeId: string, provider: string): Promise<UserTokenWithProfile[]>;
-    getTokensByScopeWithProfile(systemId: string, scopeId: string): Promise<UserTokenWithProfile[]>;
-    getTokensBySystemWithProfile(systemId: string): Promise<UserTokenWithProfile[]>;
-    findTokensByEmailInUserScopeProvider(userId: string, scopeId: string, provider: string, email: string): Promise<UserToken[]>;
-    hasTokenWithEmailInUserScopeProvider(userId: string, scopeId: string, provider: string, email: string): Promise<boolean>;
-    replaceTokensByEmailInUserScopeProvider(userId: string, scopeId: string, provider: string, email: string, newToken: Omit<UserToken, 'id' | 'createdAt' | 'updatedAt'>): Promise<UserToken>;
-    getTokenById(id: string): Promise<UserToken | null>;
-    updateToken(id: string, token: Partial<UserToken>): Promise<UserToken>;
-    deleteToken(id: string): Promise<void>;
-    deleteTokensByUser(userId: string): Promise<void>;
-    deleteTokensByUserAndScope(userId: string, scopeId: string): Promise<void>;
-    deleteTokensByUserAndProvider(userId: string, provider: string): Promise<void>;
-    saveAuthorizationState(state: AuthorizationState): Promise<void>;
-    getAuthorizationState(state: string): Promise<AuthorizationState | null>;
-    deleteAuthorizationState(state: string): Promise<void>;
-    cleanupExpiredStates(expiryMs: number): Promise<void>;
-}
 
 interface UserProfile {
     email: string;
@@ -179,190 +102,17 @@ interface ProfileFetcher {
     getProfileEndpoint(): string;
 }
 
-interface AuthorizationUrlStrategy {
-    generateAuthorizationUrl(config: OAuth2Config, state: string, codeChallenge?: string): string;
-}
-
-interface TokenExchangeStrategy {
-    exchangeCodeForToken(code: string, config: OAuth2Config, codeVerifier?: string): Promise<OAuth2Token>;
-    refreshToken(refreshToken: string, config: OAuth2Config): Promise<OAuth2Token>;
-}
-
-declare abstract class BaseProfileFetcher {
-    protected profileEndpoint: string;
-    constructor(profileEndpoint: string);
-    /**
-     * Fetch user profile information from the OAuth provider
-     * @param accessToken The OAuth access token
-     * @returns Promise resolving to standardized user profile
-     */
-    fetchUserInfo(accessToken: string): Promise<UserProfile>;
-    /**
-     * Map the raw API response to our standardized UserProfile structure
-     * Override this method to customize mapping for different providers
-     */
-    protected abstract mapToUserProfile(rawData: any): UserProfile;
-    /**
-     * Get additional headers if needed for the profile request
-     * Override this method to add provider-specific headers
-     */
-    protected getAdditionalHeaders(): Record<string, string>;
-    /**
-     * Get the profile endpoint URL
-     */
-    getEndpoint(): string;
-}
-
-declare abstract class OAuth2Provider {
-    protected config: OAuth2Config;
-    protected authUrlStrategy: AuthorizationUrlStrategy;
-    protected tokenStrategy: TokenExchangeStrategy;
-    protected profileFetcher?: BaseProfileFetcher;
-    constructor(config: OAuth2Config, authUrlStrategy?: AuthorizationUrlStrategy, tokenStrategy?: TokenExchangeStrategy, profileFetcher?: BaseProfileFetcher);
-    protected abstract createAuthorizationUrlStrategy(): AuthorizationUrlStrategy;
-    protected abstract createTokenExchangeStrategy(): TokenExchangeStrategy;
-    fetchProfile(accessToken: string): Promise<UserProfile>;
-    getProfileEndpoint(): string;
-    setProfileFetcher(profileFetcher: BaseProfileFetcher): void;
-    hasProfileFetcher(): boolean;
-    generateAuthorizationUrl(state: string, codeChallenge?: string): string;
-    exchangeCodeForToken(code: string, codeVerifier?: string): Promise<OAuth2Token>;
-    refreshToken(refreshToken: string): Promise<OAuth2Token>;
-}
-
-interface OAuth2GranularOperations {
-    createUserInSystem(systemId: string, options: UserCreationOptions): Promise<User>;
-    getOrCreateUserInSystem(systemId: string, options: UserCreationOptions): Promise<User>;
-    getUserById(userId: string): Promise<User | null>;
-    findUserByEmailInSystem(systemId: string, email: string): Promise<User | null>;
-    findUserByExternalIdInSystem(systemId: string, externalId: string): Promise<User | null>;
-    getUsersBySystem(systemId: string): Promise<User[]>;
-    saveTokenForUser(userId: string, systemId: string, scopeId: string, provider: string, email: string, token: OAuth2Token): Promise<UserToken>;
-    getTokensByUser(userId: string): Promise<UserToken[]>;
-    getTokensByUserAndScope(userId: string, scopeId: string): Promise<UserToken[]>;
-    getTokensByUserAndProvider(userId: string, provider: string): Promise<UserToken[]>;
-    getTokensByUserScopeProvider(userId: string, scopeId: string, provider: string): Promise<UserToken[]>;
-    getTokensByScope(systemId: string, scopeId: string): Promise<UserToken[]>;
-    getTokensByProvider(systemId: string, provider: string): Promise<UserToken[]>;
-    getTokensBySystem(systemId: string): Promise<UserToken[]>;
-    findTokensByEmail(email: string, systemId: string): Promise<UserToken[]>;
-    findTokensByEmailAndScope(email: string, systemId: string, scopeId: string): Promise<UserToken[]>;
-    findTokensByEmailAndProvider(email: string, systemId: string, provider: string): Promise<UserToken[]>;
-    findTokenByEmailScopeProvider(email: string, systemId: string, scopeId: string, provider: string): Promise<UserToken | null>;
-    getValidTokenByEmail(email: string, systemId: string, scopeId: string, provider: string, options?: TokenOptions): Promise<OAuth2Token>;
-    getAccessTokenByEmail(email: string, systemId: string, scopeId: string, provider: string, options?: TokenOptions): Promise<string>;
-    withValidTokenByEmail<T>(email: string, systemId: string, scopeId: string, provider: string, callback: (accessToken: string) => Promise<T>, options?: TokenOptions): Promise<T>;
-    getAllValidTokensForUser(userId: string, options?: TokenOptions): Promise<{
-        provider: string;
-        scopeId: string;
-        token: OAuth2Token;
-        userToken: UserToken;
-    }[]>;
-    getAllValidTokensForUserScopeProvider(userId: string, scopeId: string, provider: string, options?: TokenOptions): Promise<{
-        email: string;
-        token: OAuth2Token;
-        userToken: UserToken;
-    }[]>;
-    getAllValidTokensForEmail(email: string, systemId: string, options?: TokenOptions): Promise<{
-        provider: string;
-        scopeId: string;
-        token: OAuth2Token;
-        userToken: UserToken;
-    }[]>;
-    hasTokensForUserScopeProvider(userId: string, scopeId: string, provider: string): Promise<boolean>;
-    hasTokenByEmail(email: string, systemId: string, scopeId: string, provider: string): Promise<boolean>;
-    hasTokenWithEmailInUserScopeProvider(userId: string, scopeId: string, provider: string, email: string): Promise<boolean>;
-    replaceTokensByEmailInUserScopeProvider(userId: string, scopeId: string, provider: string, email: string, token: OAuth2Token): Promise<UserToken>;
-    deleteTokensByUser(userId: string): Promise<void>;
-    deleteTokensByUserAndScope(userId: string, scopeId: string): Promise<void>;
-    deleteTokensByUserAndProvider(userId: string, provider: string): Promise<void>;
-    deleteTokensByUserScopeProvider(userId: string, scopeId: string, provider: string): Promise<void>;
-    deleteTokenByEmail(email: string, systemId: string, scopeId: string, provider: string): Promise<void>;
-    createSystem(name: string, description?: string): Promise<System>;
-    getSystem(systemId: string): Promise<System | null>;
-    createScopeInSystem(systemId: string, name: string, options?: {
-        type?: 'authentication' | 'access' | 'custom';
-        permissions?: string[];
-        isolated?: boolean;
-    }): Promise<Scope>;
-    getScope(scopeId: string): Promise<Scope | null>;
-    getScopesBySystem(systemId: string): Promise<Scope[]>;
-}
-declare class OAuth2GranularClient implements OAuth2GranularOperations {
-    private storage;
-    private providers;
-    private now;
-    constructor(storage: StorageAdapter, providers: Map<string, OAuth2Provider>, now?: () => number);
-    createUserInSystem(systemId: string, options?: UserCreationOptions): Promise<User>;
-    getOrCreateUserInSystem(systemId: string, options?: UserCreationOptions): Promise<User>;
-    getUserById(userId: string): Promise<User | null>;
-    findUserByEmailInSystem(systemId: string, email: string): Promise<User | null>;
-    findUserByExternalIdInSystem(systemId: string, externalId: string): Promise<User | null>;
-    getUsersBySystem(systemId: string): Promise<User[]>;
-    saveTokenForUser(userId: string, systemId: string, scopeId: string, provider: string, email: string, token: OAuth2Token): Promise<UserToken>;
-    getTokensByUser(userId: string): Promise<UserToken[]>;
-    getTokensByUserAndScope(userId: string, scopeId: string): Promise<UserToken[]>;
-    getTokensByUserAndProvider(userId: string, provider: string): Promise<UserToken[]>;
-    getTokensByUserScopeProvider(userId: string, scopeId: string, provider: string): Promise<UserToken[]>;
-    getTokensByScope(systemId: string, scopeId: string): Promise<UserToken[]>;
-    getTokensByProvider(systemId: string, provider: string): Promise<UserToken[]>;
-    getTokensBySystem(systemId: string): Promise<UserToken[]>;
-    findTokensByEmail(email: string, systemId: string): Promise<UserToken[]>;
-    findTokensByEmailAndScope(email: string, systemId: string, scopeId: string): Promise<UserToken[]>;
-    findTokensByEmailAndProvider(email: string, systemId: string, provider: string): Promise<UserToken[]>;
-    findTokenByEmailScopeProvider(email: string, systemId: string, scopeId: string, provider: string): Promise<UserToken | null>;
-    getValidTokenByEmail(email: string, systemId: string, scopeId: string, provider: string, options?: TokenOptions): Promise<OAuth2Token>;
-    getAccessTokenByEmail(email: string, systemId: string, scopeId: string, provider: string, options?: TokenOptions): Promise<string>;
-    getAllValidTokensForUser(userId: string, options?: TokenOptions): Promise<{
-        provider: string;
-        scopeId: string;
-        token: OAuth2Token;
-        userToken: UserToken;
-    }[]>;
-    getAllValidTokensForUserScopeProvider(userId: string, scopeId: string, provider: string, options?: TokenOptions): Promise<{
-        email: string;
-        token: OAuth2Token;
-        userToken: UserToken;
-    }[]>;
-    getAllValidTokensForEmail(email: string, systemId: string, options?: TokenOptions): Promise<{
-        provider: string;
-        scopeId: string;
-        token: OAuth2Token;
-        userToken: UserToken;
-    }[]>;
-    withValidTokenByEmail<T>(email: string, systemId: string, scopeId: string, provider: string, callback: (accessToken: string) => Promise<T>, options?: TokenOptions): Promise<T>;
-    hasTokensForUserScopeProvider(userId: string, scopeId: string, provider: string): Promise<boolean>;
-    hasTokenByEmail(email: string, systemId: string, scopeId: string, provider: string): Promise<boolean>;
-    hasTokenWithEmailInUserScopeProvider(userId: string, scopeId: string, provider: string, email: string): Promise<boolean>;
-    replaceTokensByEmailInUserScopeProvider(userId: string, scopeId: string, provider: string, email: string, token: OAuth2Token): Promise<UserToken>;
-    deleteTokensByUser(userId: string): Promise<void>;
-    deleteTokensByUserAndScope(userId: string, scopeId: string): Promise<void>;
-    deleteTokensByUserAndProvider(userId: string, provider: string): Promise<void>;
-    deleteTokensByUserScopeProvider(userId: string, scopeId: string, provider: string): Promise<void>;
-    deleteTokenByEmail(email: string, systemId: string, scopeId: string, provider: string): Promise<void>;
-    createSystem(name: string, description?: string): Promise<System>;
-    getSystem(systemId: string): Promise<System | null>;
-    createScopeInSystem(systemId: string, name: string, options?: {
-        type?: 'authentication' | 'access' | 'custom';
-        permissions?: string[];
-        isolated?: boolean;
-    }): Promise<Scope>;
-    getScope(scopeId: string): Promise<Scope | null>;
-    getScopesBySystem(systemId: string): Promise<Scope[]>;
-    private isTokenExpired;
-}
-
 interface OAuth2Options {
     storage?: StorageAdapter;
-    sealKey?: string;
     providers?: Record<string, OAuth2Config>;
 }
 interface AuthorizationOptions {
     provider: string;
+    userId: string;
+    email: string;
     scopes?: string[];
     metadata?: Record<string, any>;
     usePKCE?: boolean;
-    userId?: string;
 }
 interface TokenOptions {
     autoRefresh?: boolean;
@@ -370,22 +120,8 @@ interface TokenOptions {
     expirationBuffer?: number;
     defaultExpiresIn?: number;
 }
-interface UserCreationOptions {
-    email?: string;
-    externalId?: string;
-    metadata?: Record<string, any>;
-}
-interface CallbackOptions {
-    userId?: string;
-    scopeId?: string;
-    profileOptions?: ProfileBasedTokenOptions;
-}
 interface CallbackResult {
-    userToken: UserToken;
-    userId: string;
-    systemId: string;
-    scopeId: string;
-    provider: string;
+    token: StoredToken;
     profile?: UserProfile;
 }
 declare class OAuth2Client {
@@ -394,319 +130,123 @@ declare class OAuth2Client {
     private providers;
     private providerConfigs;
     private now;
-    private currentSystem?;
-    private currentUser?;
-    private defaultScope?;
-    readonly granular: OAuth2GranularOperations;
     constructor(options?: OAuth2Options);
-    /**
-     * Quick setup for common use cases
-     */
-    static quickSetup(appName: string, providers: Record<string, OAuth2Config>): Promise<OAuth2Client>;
     /**
      * Register a provider configuration
      */
     registerProvider(name: string, config: OAuth2Config): void;
     /**
-     * Create or select a system to work with
-     */
-    createSystem(name: string, description?: string): Promise<System>;
-    useSystem(systemId: string): Promise<void>;
-    /**
-     * Create a scope within the current system
-     */
-    createScope(name: string, options?: {
-        type?: 'authentication' | 'access' | 'custom';
-        permissions?: string[];
-        isolated?: boolean;
-    }): Promise<Scope>;
-    setDefaultScope(scopeId: string): void;
-    /**
-     * Create a user (legacy method - always creates new user)
-     * @deprecated Use getOrCreateUser for better user management
-     */
-    createUser(metadata?: Record<string, any>): Promise<User>;
-    /**
-     * Get or create a user (recommended method)
-     */
-    getOrCreateUser(options?: UserCreationOptions): Promise<User>;
-    /**
-     * Get or create a user (stateless version for backend APIs)
-     */
-    getOrCreateUserStateless(systemId: string, options?: UserCreationOptions): Promise<User>;
-    /**
-     * Start authorization flow for a specific user (stateless backend API method)
-     */
-    authorizeForUser(userId: string, provider: string, options?: {
-        systemId?: string;
-        scopeId?: string;
-        scopes?: string[];
-        metadata?: Record<string, any>;
-        usePKCE?: boolean;
-    }): Promise<{
-        url: string;
-        state: string;
-    }>;
-    /**
-     * Complete workflow: get/create user and start authorization (for backend APIs)
-     */
-    createUserAndAuthorize(systemId: string, provider: string, userOptions: UserCreationOptions, authOptions?: {
-        scopeId?: string;
-        scopes?: string[];
-        metadata?: Record<string, any>;
-        usePKCE?: boolean;
-    }): Promise<{
-        user: User;
-        authUrl: string;
-        state: string;
-    }>;
-    /**
-     * Find user by email
-     */
-    findUserByEmail(email: string): Promise<User | null>;
-    /**
-     * Find user by email (stateless version)
-     */
-    findUserByEmailStateless(systemId: string, email: string): Promise<User | null>;
-    /**
-     * Find user by external ID
-     */
-    findUserByExternalId(externalId: string): Promise<User | null>;
-    /**
-     * Find user by external ID (stateless version)
-     */
-    findUserByExternalIdStateless(systemId: string, externalId: string): Promise<User | null>;
-    useUser(userId: string): Promise<void>;
-    /**
-     * Start the OAuth authorization flow
+     * Start OAuth2 authorization flow
      */
     authorize(options: AuthorizationOptions): Promise<{
         url: string;
         state: string;
     }>;
     /**
-     * Handle the OAuth callback
-     */
-    handleCallback(code: string, state: string, options?: CallbackOptions): Promise<CallbackResult>;
-    /**
-     * Merge user data from OAuth profile
-     */
-    private mergeUserDataFromProfile;
-    /**
-     * Fetch user profile for a given provider and user
-     * Note: If user has multiple tokens for the provider, this will fail.
-     * Use fetchUserProfileByEmail() for unambiguous profile fetching.
-     */
-    fetchUserProfile(provider: string, userId?: string): Promise<UserProfile>;
-    /**
-     * Fetch user profile by email (unambiguous)
-     */
-    fetchUserProfileByEmail(provider: string, email: string, systemId?: string, scopeId?: string): Promise<UserProfile>;
-    /**
-     * Replace tokens for users with conflicting email addresses
-     */
-    replaceConflictingTokensByEmail(email: string, provider: string, newUserId: string, newToken: OAuth2Token): Promise<UserToken>;
-    /**
-     * Check if a token is expired
+     * Handle OAuth2 callback
      */
-    isTokenExpired(token: OAuth2Token, options?: TokenOptions): boolean;
+    handleCallback(code: string, state: string): Promise<CallbackResult>;
     /**
      * Get a valid access token (auto-refresh if needed)
-     * Uses current context (user + default scope)
      */
-    getAccessToken(provider: string, options?: TokenOptions): Promise<string>;
+    getAccessToken(provider: string, email: string, options?: TokenOptions): Promise<string>;
     /**
-     * Get access token by email (unambiguous)
+     * Get a valid token (auto-refresh if needed)
      */
-    getAccessTokenByEmail(email: string, systemId: string, scopeId: string, provider: string, options?: TokenOptions): Promise<string>;
+    getValidToken(provider: string, email: string, options?: TokenOptions): Promise<OAuth2Token>;
     /**
-     * Ensure we have a valid token, refreshing if needed
-     * Uses current context (user + default scope)
+     * Get all tokens for a user
      */
-    ensureValidToken(provider: string, options?: TokenOptions): Promise<OAuth2Token>;
+    getTokensByUserId(userId: string): Promise<StoredToken[]>;
     /**
-     * Execute a callback with a valid access token
-     * Uses current context (user + default scope)
+     * Get all tokens for an email
      */
-    withValidToken<T>(provider: string, callback: (accessToken: string) => Promise<T>, options?: TokenOptions): Promise<T>;
+    getTokensByEmail(email: string): Promise<StoredToken[]>;
     /**
-     * Get user token entity (includes all metadata) for specific user
+     * Delete a token
      */
-    getUserTokenForUser(userId: string, _systemId: string, scopeId: string, provider: string): Promise<UserToken | null>;
+    deleteToken(provider: string, email: string): Promise<boolean>;
     /**
-     * Check if token exists for specific user/provider combination
+     * Delete all expired tokens
      */
-    hasTokenForUser(userId: string, _systemId: string, scopeId: string, provider: string): Promise<boolean>;
-    /**
-     * Revoke tokens for a specific user and provider (stateless method)
-     * This removes ALL tokens for the user/scope/provider combination
-     */
-    revokeTokensForUser(userId: string, _systemId: string, scopeId: string, provider: string): Promise<void>;
-    /**
-     * Revoke tokens for a provider
-     */
-    revokeTokens(provider: string): Promise<void>;
-    /**
-     * Get all tokens for the current user
-     */
-    getUserTokens(): Promise<UserToken[]>;
-    /**
-     * Get all tokens for a user by ID with validation and auto-refresh
-     */
-    getAllValidTokensForUser(userId: string, options?: TokenOptions): Promise<{
-        provider: string;
-        scopeId: string;
-        token: OAuth2Token;
-        userToken: UserToken;
-    }[]>;
-    /**
-     * Get all valid tokens for a user by email with validation and auto-refresh
-     */
-    getAllValidTokensForEmail(email: string, systemId?: string, options?: TokenOptions): Promise<{
-        provider: string;
-        scopeId: string;
-        token: OAuth2Token;
-        userToken: UserToken;
-    }[]>;
-    /**
-     * Get specific token for an email
-     */
-    getTokenForEmail(email: string, provider: string, systemId?: string, scopeId?: string): Promise<UserToken | null>;
-    /**
-     * Get valid token for an email (with auto-refresh)
-     */
-    getValidTokenForEmail(email: string, provider: string, systemId?: string, scopeId?: string, options?: TokenOptions): Promise<OAuth2Token>;
-    /**
-     * Get valid access token for an email (with auto-refresh)
-     */
-    getAccessTokenForEmail(email: string, provider: string, systemId?: string, scopeId?: string, options?: TokenOptions): Promise<string>;
-    /**
-     * Execute a callback with a valid access token for an email
-     */
-    withValidTokenForEmail<T>(email: string, provider: string, callback: (accessToken: string) => Promise<T>, systemId?: string, scopeId?: string, options?: TokenOptions): Promise<T>;
-    /**
-     * Check if token exists for specific email/provider combination
-     */
-    hasTokenForEmail(email: string, provider: string, systemId?: string, scopeId?: string): Promise<boolean>;
-    /**
-     * Revoke tokens for a specific email and provider
-     */
-    revokeTokensForEmail(email: string, provider: string, systemId?: string, scopeId?: string): Promise<void>;
-    /**
-     * Get tokens by scope (stateless method)
-     */
-    getTokensByScope(systemId?: string, scopeId?: string): Promise<UserToken[]>;
-    /**
-     * Find token by email and scope
-     */
-    findTokenByEmailAndScope(email: string, provider: string, systemId?: string, scopeId?: string): Promise<UserToken | null>;
-    /**
-     * Find all tokens by email and scope
-     */
-    findAllTokensByEmailAndScope(email: string, provider: string, systemId?: string, scopeId?: string): Promise<UserToken[]>;
-    private detectProviderType;
+    cleanupExpiredTokens(): Promise<number>;
     /**
      * Clean up expired authorization states
      */
-    cleanup(expiryMs?: number): Promise<void>;
-    /**
-     * Get all valid tokens for a user with OAuth provider profile information (RECOMMENDED FOR UI)
-     * This fetches the actual email/profile from each OAuth provider using the access token
-     */
-    getAllValidTokensWithProviderProfiles(userId: string, options?: TokenOptions): Promise<{
-        provider: string;
-        scopeId: string;
-        token: OAuth2Token;
-        userToken: UserToken;
-        profile?: UserProfile;
-    }[]>;
+    cleanupExpiredStates(): Promise<number>;
+    private isTokenExpired;
+    private detectProviderType;
+}
+
+declare class InMemoryStorageAdapter implements StorageAdapter {
+    private tokens;
+    private states;
+    private generateId;
+    saveToken(input: SaveTokenInput): Promise<StoredToken>;
+    getToken(provider: string, email: string): Promise<StoredToken | null>;
+    getTokenById(id: string): Promise<StoredToken | null>;
+    getTokensByUserId(userId: string): Promise<StoredToken[]>;
+    getTokensByEmail(email: string): Promise<StoredToken[]>;
+    getTokensByProvider(provider: string): Promise<StoredToken[]>;
+    updateToken(id: string, update: UpdateTokenInput): Promise<StoredToken | null>;
+    deleteToken(id: string): Promise<boolean>;
+    deleteTokenByProviderEmail(provider: string, email: string): Promise<boolean>;
+    deleteExpiredTokens(): Promise<number>;
+    saveAuthorizationState(state: Omit<AuthorizationState, 'createdAt'>): Promise<AuthorizationState>;
+    getAuthorizationState(state: string): Promise<AuthorizationState | null>;
+    deleteAuthorizationState(state: string): Promise<boolean>;
+    cleanupExpiredStates(): Promise<number>;
+}
+
+interface AuthorizationUrlStrategy {
+    generateAuthorizationUrl(config: OAuth2Config, state: string, codeChallenge?: string): string;
+}
+
+interface TokenExchangeStrategy {
+    exchangeCodeForToken(code: string, config: OAuth2Config, codeVerifier?: string): Promise<OAuth2Token>;
+    refreshToken(refreshToken: string, config: OAuth2Config): Promise<OAuth2Token>;
+}
+
+declare abstract class BaseProfileFetcher {
+    protected profileEndpoint: string;
+    constructor(profileEndpoint: string);
     /**
-     * Get all valid tokens for a user and scope with OAuth provider profile information
+     * Fetch user profile information from the OAuth provider
+     * @param accessToken The OAuth access token
+     * @returns Promise resolving to standardized user profile
      */
-    getAllValidTokensForUserAndScopeWithProviderProfiles(userId: string, scopeId: string, options?: TokenOptions): Promise<{
-        provider: string;
-        token: OAuth2Token;
-        userToken: UserToken;
-        profile?: UserProfile;
-    }[]>;
+    fetchUserInfo(accessToken: string): Promise<UserProfile>;
     /**
-     * Get all valid tokens for a user and provider with OAuth provider profile information
+     * Map the raw API response to our standardized UserProfile structure
+     * Override this method to customize mapping for different providers
      */
-    getAllValidTokensForUserAndProviderWithProviderProfiles(userId: string, provider: string, options?: TokenOptions): Promise<{
-        scopeId: string;
-        token: OAuth2Token;
-        userToken: UserToken;
-        profile?: UserProfile;
-    }[]>;
+    protected abstract mapToUserProfile(rawData: any): UserProfile;
     /**
-     * Get OAuth provider profile for a specific token
-     * This fetches the actual email/profile from the OAuth provider using the access token
+     * Get additional headers if needed for the profile request
+     * Override this method to add provider-specific headers
      */
-    getTokenProfile(token: OAuth2Token, provider: string): Promise<UserProfile | null>;
+    protected getAdditionalHeaders(): Record<string, string>;
     /**
-     * Get OAuth provider profile for a specific user token
-     * This fetches the actual email/profile from the OAuth provider using the access token
+     * Get the profile endpoint URL
      */
-    getUserTokenProfile(userToken: UserToken): Promise<UserProfile | null>;
+    getEndpoint(): string;
 }
 
-declare class InMemoryStorageAdapter implements StorageAdapter {
-    private systems;
-    private scopes;
-    private users;
-    private tokens;
-    private states;
-    private generateId;
-    createSystem(system: Omit<System, 'id' | 'createdAt' | 'updatedAt'>): Promise<System>;
-    getSystem(id: string): Promise<System | null>;
-    updateSystem(id: string, updates: Partial<System>): Promise<System>;
-    deleteSystem(id: string): Promise<void>;
-    listSystems(): Promise<System[]>;
-    createScope(scope: Omit<Scope, 'id'>): Promise<Scope>;
-    getScope(id: string): Promise<Scope | null>;
-    getScopesBySystem(systemId: string): Promise<Scope[]>;
-    updateScope(id: string, updates: Partial<Scope>): Promise<Scope>;
-    deleteScope(id: string): Promise<void>;
-    createUser(user: Omit<User, 'id' | 'createdAt' | 'updatedAt'>): Promise<User>;
-    getOrCreateUser(input: CreateUserInput): Promise<User>;
-    findUserByEmail(systemId: string, email: string): Promise<User | null>;
-    findUserByExternalId(systemId: string, externalId: string): Promise<User | null>;
-    getUser(id: string): Promise<User | null>;
-    getUsersBySystem(systemId: string): Promise<User[]>;
-    updateUser(id: string, updates: Partial<User>): Promise<User>;
-    deleteUser(id: string): Promise<void>;
-    saveToken(token: Omit<UserToken, 'id' | 'createdAt' | 'updatedAt'>): Promise<UserToken>;
-    saveTokenWithEmailValidation(userId: string, systemId: string, scopeId: string, provider: string, email: string, token: Omit<UserToken, 'id' | 'createdAt' | 'updatedAt'>): Promise<UserToken>;
-    getTokensByUser(userId: string): Promise<UserToken[]>;
-    getTokensByUserAndScope(userId: string, scopeId: string): Promise<UserToken[]>;
-    getTokensByUserAndProvider(userId: string, provider: string): Promise<UserToken[]>;
-    getTokensByUserScopeProvider(userId: string, scopeId: string, provider: string): Promise<UserToken[]>;
-    getTokensByScope(systemId: string, scopeId: string): Promise<UserToken[]>;
-    getTokensByProvider(systemId: string, provider: string): Promise<UserToken[]>;
-    getTokensBySystem(systemId: string): Promise<UserToken[]>;
-    findTokensByEmail(email: string, systemId: string): Promise<UserToken[]>;
-    findTokensByEmailAndScope(email: string, systemId: string, scopeId: string): Promise<UserToken[]>;
-    findTokensByEmailAndProvider(email: string, systemId: string, provider: string): Promise<UserToken[]>;
-    findTokenByEmailScopeProvider(email: string, systemId: string, scopeId: string, provider: string): Promise<UserToken | null>;
-    findTokensByEmailInUserScopeProvider(userId: string, scopeId: string, provider: string, email: string): Promise<UserToken[]>;
-    hasTokenWithEmailInUserScopeProvider(userId: string, scopeId: string, provider: string, email: string): Promise<boolean>;
-    replaceTokensByEmailInUserScopeProvider(userId: string, scopeId: string, provider: string, email: string, newToken: Omit<UserToken, 'id' | 'createdAt' | 'updatedAt'>): Promise<UserToken>;
-    getTokenById(id: string): Promise<UserToken | null>;
-    updateToken(id: string, updates: Partial<UserToken>): Promise<UserToken>;
-    deleteToken(id: string): Promise<void>;
-    deleteTokensByUser(userId: string): Promise<void>;
-    deleteTokensByUserAndScope(userId: string, scopeId: string): Promise<void>;
-    deleteTokensByUserAndProvider(userId: string, provider: string): Promise<void>;
-    saveAuthorizationState(state: AuthorizationState): Promise<void>;
-    getAuthorizationState(state: string): Promise<AuthorizationState | null>;
-    deleteAuthorizationState(state: string): Promise<void>;
-    cleanupExpiredStates(expiryMs: number): Promise<void>;
-    getTokensByUserWithProfile(userId: string): Promise<UserTokenWithProfile[]>;
-    getTokensByUserAndScopeWithProfile(userId: string, scopeId: string): Promise<UserTokenWithProfile[]>;
-    getTokensByUserAndProviderWithProfile(userId: string, provider: string): Promise<UserTokenWithProfile[]>;
-    getTokensByUserScopeProviderWithProfile(userId: string, scopeId: string, provider: string): Promise<UserTokenWithProfile[]>;
-    getTokensByScopeWithProfile(systemId: string, scopeId: string): Promise<UserTokenWithProfile[]>;
-    getTokensBySystemWithProfile(systemId: string): Promise<UserTokenWithProfile[]>;
+declare abstract class OAuth2Provider {
+    protected config: OAuth2Config;
+    protected authUrlStrategy: AuthorizationUrlStrategy;
+    protected tokenStrategy: TokenExchangeStrategy;
+    protected profileFetcher?: BaseProfileFetcher;
+    constructor(config: OAuth2Config, authUrlStrategy?: AuthorizationUrlStrategy, tokenStrategy?: TokenExchangeStrategy, profileFetcher?: BaseProfileFetcher);
+    protected abstract createAuthorizationUrlStrategy(): AuthorizationUrlStrategy;
+    protected abstract createTokenExchangeStrategy(): TokenExchangeStrategy;
+    fetchProfile(accessToken: string): Promise<UserProfile>;
+    getProfileEndpoint(): string;
+    setProfileFetcher(profileFetcher: BaseProfileFetcher): void;
+    hasProfileFetcher(): boolean;
+    generateAuthorizationUrl(state: string, codeChallenge?: string): string;
+    exchangeCodeForToken(code: string, codeVerifier?: string): Promise<OAuth2Token>;
+    refreshToken(refreshToken: string): Promise<OAuth2Token>;
 }
 
 type ProviderType = 'google' | 'github' | 'microsoft' | 'outlook' | 'facebook' | 'generic';
@@ -782,4 +322,4 @@ declare const generateState: () => string;
 declare const seal: <T>(d: T, key: string) => Promise<string>;
 declare const unseal: <T>(s: string, key: string) => Promise<T>;
 
-export { type AuthorizationState, type AuthorizationUrlStrategy, BaseProfileFetcher, type CreateUserInput, GenericOAuth2Provider, GenericProfileFetcher, GitHubProfileFetcher, GoogleProfileFetcher, InMemoryStorageAdapter, MicrosoftProfileFetcher, OAuth2Client, type OAuth2Config, OAuth2GranularClient, OAuth2Provider, type OAuth2Token, type ProfileFetcher, ProfileFetcherFactory, type ProfileFetcherOptions, type ProfileMapping, type ProviderFactory, type ProviderType, type Scope, StandardAuthorizationUrlStrategy, StandardTokenExchangeStrategy, type StorageAdapter, type System, type TokenExchangeStrategy, type User, type UserProfile, type UserToken, type UserTokenWithProfile, createCodeChallenge, createCodeVerifier, generateState, seal, unseal };
+export { type AuthorizationOptions, type AuthorizationState, type AuthorizationUrlStrategy, BaseProfileFetcher, type CallbackResult, GenericOAuth2Provider, GenericProfileFetcher, GitHubProfileFetcher, GoogleProfileFetcher, InMemoryStorageAdapter, MicrosoftProfileFetcher, OAuth2Client, type OAuth2Config, type OAuth2Options, OAuth2Provider, type OAuth2Token, type ProfileBasedTokenOptions, type ProfileFetcher, ProfileFetcherFactory, type ProfileFetcherOptions, type ProfileMapping, type ProviderFactory, type ProviderType, type SaveTokenInput, StandardAuthorizationUrlStrategy, StandardTokenExchangeStrategy, type StorageAdapter, type StoredToken, type TokenExchangeStrategy, type TokenOptions, type UpdateTokenInput, type UserProfile, createCodeChallenge, createCodeVerifier, generateState, seal, unseal };