import { CredentialStore } from "../types/server.js";

//#region src/credential-stores/keychain-store.d.ts

/**
 * KeyChainStore - Cross-platform system keychain credential storage
 *
 * Uses the native OS credential storage:
 * - macOS: Keychain
 * - Windows: Credential Vault
 * - Linux: Secret Service API/libsecret
 *
 * Requires the '@napi-rs/keyring' npm package to be installed.
 * Falls back gracefully if keyring is not available.
 *
 * ## macOS Permission Handling
 *
 * On macOS, when your Node.js app first calls keyring operations:
 * - `setPassword()` creates a new Keychain item (no prompt required)
 * - `getPassword()` may prompt the user for permission on first access
 * - Users can click "Allow", "Always Allow", or "Deny"
 * - If denied, keyring returns `null` which this implementation handles gracefully
 * - The calling binary (usually `node`) will be shown in the permission prompt
 * - For better UX in packaged apps, consider code signing and app bundling
 *
 * This implementation handles all permission scenarios gracefully:
 * - Returns `null` when access is denied or credentials don't exist
 * - Logs errors for debugging permission issues
 * - Never throws on permission denial, only on system-level errors
 */
declare class KeyChainStore implements CredentialStore {
  readonly id: string;
  readonly type: "keychain";
  private readonly service;
  private readonly logger;
  private keyringAvailable;
  private EntryClass;
  private initializationPromise;
  constructor(id: string, servicePrefix?: string);
  /**
   * Initialize keyring dynamically to handle optional availability
   */
  private initializeKeyring;
  /**
   * Add a key to the index
   */
  private addKeyToIndex;
  /**
   * Remove a key from the index
   */
  private removeKeyFromIndex;
  /**
   * Get a credential from the keychain
   */
  get(key: string): Promise<string | null>;
  /**
   * Set a credential in the keychain
   */
  set(key: string, value: string, /** Optional metadata (ignored by keychain store) */
  _metadata?: Record<string, string>): Promise<void>;
  /**
   * Check if a credential exists in the keychain
   */
  has(key: string): Promise<boolean>;
  /**
   * Check if the credential store is available and functional
   */
  checkAvailability(): Promise<{
    available: boolean;
    reason?: string;
  }>;
  /**
   * Delete a credential from the keychain
   */
  delete(key: string): Promise<boolean>;
  /**
   * Find all credentials for this service
   * Useful for debugging and listing stored credentials
   *
   * NOTE: @napi-rs/keyring does not have a findCredentials equivalent.
   * This implementation uses a key index to track all stored keys.
   * The index is maintained separately and updated during set/delete operations.
   */
  findAllCredentials(): Promise<Array<{
    account: string;
    password: string;
  }>>;
  /**
   * Clear all credentials for this service
   * WARNING: This will delete all credentials stored under this service
   */
  clearAll(): Promise<number>;
}
/**
 * Factory function to create KeyChainStore
 * Provides consistent initialization and optional configuration
 *
 * ## Usage Recommendations for macOS Permission Handling
 *
 * 1. **First-time setup**: Inform users that they may see permission prompts
 * 2. **Error handling**: Check for `null` returns from `get()` operations
 * 3. **User guidance**: If credentials can't be retrieved, guide users to:
 *    - Check Keychain Access app for denied permissions
 *    - Re-run the application if they accidentally clicked "Deny"
 * 4. **Development**: Use a consistent `servicePrefix` to avoid permission prompt spam
 * 5. **Production**: Consider code-signing your distributed app for better permission prompts
 *
 * Example usage with permission handling:
 * ```typescript
 * const store = createKeyChainStore('my-app');
 *
 * // Always check for null when retrieving
 * const apiKey = await store.get('api-key');
 * if (!apiKey) {
 *   console.log('API key not found or access denied');
 *   // Guide user to check permissions or re-enter credentials
 * }
 * ```
 */
declare function createKeyChainStore(id: string, options?: {
  servicePrefix?: string;
}): KeyChainStore;
//#endregion
export { KeyChainStore, createKeyChainStore };