import type { IAuthToken, ICredentials, TRegistryProtocol } from './interfaces.core.js';

/**
 * Options for creating a token
 */
export interface ITokenOptions {
  /** Whether the token is readonly */
  readonly?: boolean;
  /** Permission scopes */
  scopes?: string[];
  /** Expiration time in seconds */
  expiresIn?: number;
}

/**
 * Pluggable authentication provider interface.
 * Implement this to integrate external auth systems (LDAP, OAuth, SSO, OIDC).
 *
 * @example
 * ```typescript
 * class LdapAuthProvider implements IAuthProvider {
 *   constructor(private ldap: LdapClient, private redis: RedisClient) {}
 *
 *   async authenticate(credentials: ICredentials): Promise<string | null> {
 *     return await this.ldap.bind(credentials.username, credentials.password);
 *   }
 *
 *   async validateToken(token: string): Promise<IAuthToken | null> {
 *     return await this.redis.get(`token:${token}`);
 *   }
 *   // ...
 * }
 * ```
 */
export interface IAuthProvider {
  /**
   * Initialize the auth provider (optional)
   */
  init?(): Promise<void>;

  /**
   * Authenticate user credentials (login flow)
   * @param credentials - Username and password
   * @returns User ID on success, null on failure
   */
  authenticate(credentials: ICredentials): Promise<string | null>;

  /**
   * Validate an existing token
   * @param token - Token string (UUID or JWT)
   * @param protocol - Optional protocol hint for optimization
   * @returns Auth token info or null if invalid
   */
  validateToken(token: string, protocol?: TRegistryProtocol): Promise<IAuthToken | null>;

  /**
   * Create a new token for a user
   * @param userId - User ID
   * @param protocol - Protocol type (npm, oci, maven, etc.)
   * @param options - Token options (readonly, scopes, expiration)
   * @returns Token string
   */
  createToken(userId: string, protocol: TRegistryProtocol, options?: ITokenOptions): Promise<string>;

  /**
   * Revoke a token
   * @param token - Token string to revoke
   */
  revokeToken(token: string): Promise<void>;

  /**
   * Check if user has permission for an action
   * @param token - Auth token (or null for anonymous)
   * @param resource - Resource being accessed (e.g., "npm:package:lodash")
   * @param action - Action being performed (read, write, push, pull, delete)
   * @returns true if authorized
   */
  authorize(token: IAuthToken | null, resource: string, action: string): Promise<boolean>;

  /**
   * List all tokens for a user (optional)
   * @param userId - User ID
   * @returns List of token info
   */
  listUserTokens?(userId: string): Promise<Array<{
    key: string;
    readonly: boolean;
    created: string;
    protocol?: TRegistryProtocol;
  }>>;
}