/**
 * Authentication Strategy Interface
 * Base interface for OAuth/OIDC and LDAP authentication strategies
 */

import type {
  IExternalUserInfo,
  IConnectionTestResult,
} from '../../../interfaces/auth.interfaces.ts';

export interface IOAuthCallbackData {
  code: string;
  state: string;
  error?: string;
  errorDescription?: string;
}

export interface IAuthStrategy {
  /**
   * Get the authorization URL for OAuth/OIDC flow
   * @param state - CSRF state token
   * @param nonce - Optional nonce for OIDC
   * @returns Authorization URL to redirect user to
   */
  getAuthorizationUrl?(state: string, nonce?: string): Promise<string>;

  /**
   * Handle OAuth/OIDC callback
   * @param data - Callback data including code and state
   * @returns External user info from the provider
   */
  handleCallback?(data: IOAuthCallbackData): Promise<IExternalUserInfo>;

  /**
   * Authenticate with credentials (LDAP)
   * @param username - Username
   * @param password - Password
   * @returns External user info if authentication succeeds
   */
  authenticateCredentials?(username: string, password: string): Promise<IExternalUserInfo>;

  /**
   * Test connection to the provider
   * @returns Connection test result
   */
  testConnection(): Promise<IConnectionTestResult>;
}