fix(ssh): reason-aware auth-failure messages and lazy TOTP retry (#1018)

* fix(ssh): reason-aware auth-failure messages and lazy TOTP retry

* fix(ssh): drop em-dash and AI-vibe wording from auth-failure strings

Author: datlechin

CHANGELOG.md

@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- SSH auth-failure alerts now point at the actual cause. The catch-all "Check your credentials or private key." string was wrong for the most common 2FA case (typing a wrong TOTP code), because the credentials were fine; only the verification code was wrong. `SSHTunnelError.authenticationFailed` now carries an `AuthFailureReason` (`password`, `verificationCode`, `privateKey`, `agentRejected`, `generic`), every throw site picks the right one, and the alert text matches: "Verification code rejected. Get a new code from your authenticator app and try again." for kbd-int + TOTP rejections, "SSH password rejected. Check the password and try again." for plain password rejections, and so on. Follow-up to #1005.
+- TOTP codes are now fetched lazily from the `TOTPProvider` inside the kbd-int callback rather than once upfront before authentication starts. Fixes two related issues: (1) when the kbd-int handshake straddled a 30-second TOTP rotation boundary, the `AutoTOTPProvider` code that was valid at fetch time had expired by the time PAM validated it; (2) when the server retried after a wrong code (sshd defaults to 3 prompts per session), TablePro replayed the same wrong code instead of asking the user for a new one. `PromptTOTPProvider` now switches its NSAlert wording to "Verification Code Rejected. The previous code wasn't accepted. Wait for your authenticator to refresh, then enter the new code." on retries, matching how OpenSSH re-prompts.
 - SSH Auth Method = Password failed against servers that only advertise `keyboard-interactive` (the typical `pam_google_authenticator` setup, where `sshd_config` has `AuthenticationMethods keyboard-interactive`). The bare `userauth_password` request the server doesn't accept was the only attempt, so connection failed even when the user typed the right password. `buildAuthenticator` now always pairs `PasswordAuthenticator` with a `KeyboardInteractiveAuthenticator` that reuses the same password, matching OpenSSH and Sequel Ace's "save the password, the server may also prompt for a code" flow. Follow-up to #1005.
 - SSH connections to servers requiring Google Authenticator (or any PAM stack that pairs `Password:` with `Verification code:` over keyboard-interactive) failed when the user picked Auth Method = Password with TOTP enabled. `LibSSH2TunnelFactory.buildAuthenticator` built a `CompositeAuthenticator(PasswordAuthenticator → KeyboardInteractiveAuthenticator)` but passed `password: nil` to the kbd-interactive fallback, so when the server replayed the password challenge the callback answered with an empty string. The fallback now reuses the same SSH password, mirroring the `.keyboardInteractive` path. Fixes #1005.
 - Up arrow on the first line of the SQL editor failed to jump to the start of the document when the caret was at the very end of a single-line query (or anywhere outside the half-open `lineStorage.first.range`). Same shape on the symmetric Down-on-last-line path. The first/last-line detection used `NSRange.contains`, which is half-open and excludes the trailing offset, so the caret-at-end-of-document fell through to a geometry probe that found no line above and bailed. Now the check uses `textLineForOffset`, which already handles `offset == length` by returning the last line, and compares line IDs.

TablePro/Core/SSH/Auth/AgentAuthenticator.swift

@@ -110,6 +110,6 @@ internal struct AgentAuthenticator: SSHAuthenticator {
         }
 
         Self.logger.error("SSH agent authentication failed: no identity accepted")
-        throw SSHTunnelError.authenticationFailed
+        throw SSHTunnelError.authenticationFailed(reason: .agentRejected)
     }
 }

TablePro/Core/SSH/Auth/CompositeAuthenticator.swift

@@ -33,7 +33,7 @@ internal struct CompositeAuthenticator: SSHAuthenticator {
         }
 
         if libssh2_userauth_authenticated(session) == 0 {
-            throw lastError ?? SSHTunnelError.authenticationFailed
+            throw lastError ?? SSHTunnelError.authenticationFailed(reason: .generic)
         }
     }
 }

TablePro/Core/SSH/Auth/KeyboardInteractiveAuthenticator.swift

@@ -15,14 +15,38 @@ internal enum KBDINTPromptType {
     case unknown
 }
 
-/// Context passed through the libssh2 session abstract pointer to the C callback
+/// Context passed through the libssh2 session abstract pointer to the C callback.
+///
+/// TOTP codes are fetched lazily inside the callback (not upfront) so that:
+///  - `AutoTOTPProvider` generates a code that's still valid when PAM validates it. The
+///    upfront approach raced the 30-second window during the SSH handshake.
+///  - When the server retries the kbd-int session after a wrong code (PAM defaults to
+///    3 prompts), each retry calls `provideCode(attempt:)` again, matching how OpenSSH
+///    re-prompts the user.
 internal final class KeyboardInteractiveContext {
-    var password: String?
-    var totpCode: String?
+    let password: String?
+    let totpProvider: (any TOTPProvider)?
+    var totpAttemptCount: Int = 0
+    var lastTotpError: Error?
 
-    init(password: String?, totpCode: String?) {
+    init(password: String?, totpProvider: (any TOTPProvider)?) {
         self.password = password
-        self.totpCode = totpCode
+        self.totpProvider = totpProvider
+    }
+
+    /// Fetches the next TOTP code. Errors from the provider (user cancelled, missing
+    /// secret) are stored in `lastTotpError` and surface at the end of the kbd-int session.
+    /// The C callback can't throw across the libssh2 boundary, so we record the failure
+    /// and report it after `libssh2_userauth_keyboard_interactive_ex` returns.
+    func nextTotpCode() -> String {
+        guard let totpProvider else { return "" }
+        defer { totpAttemptCount += 1 }
+        do {
+            return try totpProvider.provideCode(attempt: totpAttemptCount)
+        } catch {
+            lastTotpError = error
+            return ""
+        }
     }
 }
 
@@ -67,7 +91,7 @@ private let kbdintCallback: @convention(c) (
         case .password:
             responseText = context.password ?? ""
         case .totp:
-            responseText = context.totpCode ?? ""
+            responseText = context.nextTotpCode()
         case .unknown:
             // Fall back to password for unrecognized prompts
             responseText = context.password ?? ""
@@ -89,16 +113,9 @@ internal struct KeyboardInteractiveAuthenticator: SSHAuthenticator {
     let totpProvider: (any TOTPProvider)?
 
     func authenticate(session: OpaquePointer, username: String) throws {
-        // Generate TOTP code if a provider is available
-        let totpCode: String?
-        if let totpProvider {
-            totpCode = try totpProvider.provideCode()
-        } else {
-            totpCode = nil
-        }
-
-        // Create context and store in session abstract pointer
-        let context = KeyboardInteractiveContext(password: password, totpCode: totpCode)
+        // Hand the provider to the callback so it can fetch a fresh code on every challenge
+        // (see KeyboardInteractiveContext doc comment for why this isn't done upfront).
+        let context = KeyboardInteractiveContext(password: password, totpProvider: totpProvider)
         let contextPtr = Unmanaged.passRetained(context).toOpaque()
 
         defer {
@@ -124,13 +141,22 @@ internal struct KeyboardInteractiveAuthenticator: SSHAuthenticator {
             kbdintCallback
         )
 
+        // Surface a totpProvider error (e.g. user cancelled the NSAlert) verbatim. It's
+        // already an SSHTunnelError with the right reason.
+        if let providerError = context.lastTotpError {
+            throw providerError
+        }
+
         guard rc == 0 else {
             var msgPtr: UnsafeMutablePointer<CChar>?
             var msgLen: Int32 = 0
             libssh2_session_last_error(session, &msgPtr, &msgLen, 0)
             let detail = msgPtr.map { String(cString: $0) } ?? "Unknown error"
             Self.logger.error("Keyboard-interactive authentication failed: \(detail)")
-            throw SSHTunnelError.authenticationFailed
+            // If a TOTP code was actually delivered to the server, the rejection is most
+            // likely about that code. Point the user at the authenticator, not the password.
+            let reason: AuthFailureReason = context.totpAttemptCount > 0 ? .verificationCode : .password
+            throw SSHTunnelError.authenticationFailed(reason: reason)
         }
 
         Self.logger.info("Keyboard-interactive authentication succeeded")

TablePro/Core/SSH/Auth/PasswordAuthenticator.swift

@@ -26,7 +26,7 @@ internal struct PasswordAuthenticator: SSHAuthenticator {
             libssh2_session_last_error(session, &msgPtr, &msgLen, 0)
             let detail = msgPtr.map { String(cString: $0) } ?? "Unknown error"
             Self.logger.error("Password authentication failed: \(detail)")
-            throw SSHTunnelError.authenticationFailed
+            throw SSHTunnelError.authenticationFailed(reason: .password)
         }
     }
 }

TablePro/Core/SSH/Auth/PromptTOTPProvider.swift

@@ -11,21 +11,23 @@ import Foundation
 /// This provider blocks the calling thread while the alert is displayed on the main thread.
 /// It is intended for interactive SSH sessions where no TOTP secret is configured.
 internal final class PromptTOTPProvider: TOTPProvider, @unchecked Sendable {
-    func provideCode() throws -> String {
+    func provideCode(attempt: Int) throws -> String {
         if Thread.isMainThread {
-            return try handleResult(showAlert())
+            return try handleResult(showAlert(attempt: attempt))
         }
-        return try handleResult(DispatchQueue.main.sync { showAlert() })
+        return try handleResult(DispatchQueue.main.sync { showAlert(attempt: attempt) })
     }
 
     // Note: runModal() is intentional here. This method runs on the main thread
     // (via DispatchQueue.main.sync from provideCode), so beginSheetModal + semaphore would deadlock.
-    private func showAlert() -> String? {
+    private func showAlert(attempt: Int) -> String? {
         let alert = NSAlert()
-        alert.messageText = String(localized: "Verification Code Required")
-        alert.informativeText = String(
-            localized: "Enter the TOTP verification code for SSH authentication."
-        )
+        alert.messageText = attempt == 0
+            ? String(localized: "Verification Code Required")
+            : String(localized: "Verification Code Rejected")
+        alert.informativeText = attempt == 0
+            ? String(localized: "Enter the TOTP verification code for SSH authentication.")
+            : String(localized: "The previous code wasn't accepted. Wait for your authenticator to refresh, then enter the new code.")
         alert.alertStyle = .informational
         alert.addButton(withTitle: String(localized: "Connect"))
         alert.addButton(withTitle: String(localized: "Cancel"))
@@ -41,7 +43,7 @@ internal final class PromptTOTPProvider: TOTPProvider, @unchecked Sendable {
 
     private func handleResult(_ code: String?) throws -> String {
         guard let totpCode = code, !totpCode.isEmpty else {
-            throw SSHTunnelError.authenticationFailed
+            throw SSHTunnelError.authenticationFailed(reason: .verificationCode)
         }
         return totpCode
     }

TablePro/Core/SSH/Auth/TOTPProvider.swift

@@ -7,10 +7,19 @@ import Foundation
 
 /// Protocol for providing TOTP verification codes
 internal protocol TOTPProvider: Sendable {
-    /// Generate or obtain a TOTP code
-    /// - Returns: The TOTP code string
-    /// - Throws: SSHTunnelError if the code cannot be obtained
-    func provideCode() throws -> String
+    /// Generate or obtain a TOTP code.
+    /// - Parameter attempt: 0 for the first prompt in a session, 1+ for retries when the
+    ///   server rejected an earlier code (wrong digits, expired window). Implementations
+    ///   may use this to vary UI affordances. `PromptTOTPProvider` shows a "previous code
+    ///   was rejected" hint when `attempt > 0`.
+    /// - Returns: The TOTP code string.
+    /// - Throws: `SSHTunnelError` if the code cannot be obtained (user cancelled, no secret).
+    func provideCode(attempt: Int) throws -> String
+}
+
+extension TOTPProvider {
+    /// Convenience for callers that only ever need a single code (test connections, sync probes).
+    func provideCode() throws -> String { try provideCode(attempt: 0) }
 }
 
 /// Automatically generates TOTP codes from a stored secret.
@@ -21,7 +30,7 @@ internal protocol TOTPProvider: Sendable {
 internal struct AutoTOTPProvider: TOTPProvider {
     let generator: TOTPGenerator
 
-    func provideCode() throws -> String {
+    func provideCode(attempt: Int) throws -> String {
         let remaining = generator.secondsRemaining()
         if remaining < 5 {
             // Brief bounded sleep (max ~6s) to wait for next TOTP period.

TablePro/Core/SSH/LibSSH2TunnelFactory.swift

@@ -468,7 +468,7 @@ internal enum LibSSH2TunnelFactory {
             // Sequel Ace's behavior.
             guard let sshPassword = credentials.sshPassword else {
                 logger.error("SSH password is nil (Keychain lookup may have failed) for \(resolved.host)")
-                throw SSHTunnelError.authenticationFailed
+                throw SSHTunnelError.authenticationFailed(reason: .password)
             }
             let totpProvider = buildTOTPProvider(config: config, credentials: credentials)
             return CompositeAuthenticator(authenticators: [
@@ -479,7 +479,7 @@ internal enum LibSSH2TunnelFactory {
         case .privateKey:
             let keyPaths = effectiveKeyPaths(for: resolved)
             guard !keyPaths.isEmpty else {
-                throw SSHTunnelError.authenticationFailed
+                throw SSHTunnelError.authenticationFailed(reason: .privateKey)
             }
             var authenticators: [any SSHAuthenticator] = keyPaths.map { keyPath in
                 buildKeyFileAuthenticator(
@@ -599,11 +599,11 @@ internal enum LibSSH2TunnelFactory {
             }
 
             // 2. Prompt the user if allowed (key is encrypted, no stored passphrase)
-            guard canPrompt else { throw SSHTunnelError.authenticationFailed }
+            guard canPrompt else { throw SSHTunnelError.authenticationFailed(reason: .privateKey) }
 
             let provider = PromptPassphraseProvider(keyPath: expandedPath)
             guard let promptResult = provider.providePassphrase() else {
-                throw SSHTunnelError.authenticationFailed
+                throw SSHTunnelError.authenticationFailed(reason: .privateKey)
             }
 
             let retryAuth = PublicKeyAuthenticator(
@@ -643,7 +643,7 @@ internal enum LibSSH2TunnelFactory {
         case .privateKey:
             let keyPaths = effectiveKeyPaths(for: resolved)
             guard !keyPaths.isEmpty else {
-                throw SSHTunnelError.authenticationFailed
+                throw SSHTunnelError.authenticationFailed(reason: .privateKey)
             }
             let authenticators = keyPaths.map { path in
                 KeyFileAuthenticator(

TablePro/Core/SSH/SSHTunnelManager.swift

@@ -8,12 +8,23 @@
 import Foundation
 import os
 
+/// Why an SSH authentication attempt failed. Drives the user-facing error string so the
+/// alert points at the actual cause (wrong OTP, missing key, agent rejection) instead of
+/// the catch-all "credentials or private key" message.
+enum AuthFailureReason: Sendable, Equatable {
+    case password
+    case verificationCode
+    case privateKey
+    case agentRejected
+    case generic
+}
+
 /// Error types for SSH tunnel operations
-enum SSHTunnelError: Error, LocalizedError {
+enum SSHTunnelError: Error, LocalizedError, Equatable {
     case tunnelCreationFailed(String)
     case tunnelAlreadyExists(UUID)
     case noAvailablePort
-    case authenticationFailed
+    case authenticationFailed(reason: AuthFailureReason)
     case connectionTimeout
     case hostKeyVerificationFailed
     case channelOpenFailed
@@ -26,8 +37,19 @@ enum SSHTunnelError: Error, LocalizedError {
             return String(format: String(localized: "SSH tunnel already exists for connection: %@"), id.uuidString)
         case .noAvailablePort:
             return String(localized: "No available local port for SSH tunnel")
-        case .authenticationFailed:
-            return String(localized: "SSH authentication failed. Check your credentials or private key.")
+        case .authenticationFailed(let reason):
+            switch reason {
+            case .password:
+                return String(localized: "SSH password rejected. Check the password and try again.")
+            case .verificationCode:
+                return String(localized: "Verification code rejected. Get a new code from your authenticator app and try again.")
+            case .privateKey:
+                return String(localized: "SSH private key rejected. Check the key file or passphrase.")
+            case .agentRejected:
+                return String(localized: "SSH agent did not authenticate. Run ssh-add -l to check loaded keys.")
+            case .generic:
+                return String(localized: "SSH authentication failed. Check your credentials or private key.")
+            }
         case .connectionTimeout:
             return String(localized: "SSH connection timed out")
         case .hostKeyVerificationFailed:

TablePro/Resources/Localizable.xcstrings

@@ -43304,6 +43304,9 @@
           }
         }
       }
+    },
+    "SSH agent did not authenticate. Make sure the right key is loaded (try ssh-add -l)." : {
+
     },
     "SSH authentication failed. Check your credentials or private key." : {
       "localizations" : {
@@ -43485,6 +43488,9 @@
           }
         }
       }
+    },
+    "SSH password rejected. Check the password for this connection." : {
+
     },
     "SSH Port" : {
       "localizations" : {
@@ -43510,6 +43516,9 @@
     },
     "SSH port must be between 1 and 65535" : {
 
+    },
+    "SSH private key rejected. Check the key file, passphrase, or pick a different identity." : {
+
     },
     "SSH Profile" : {
       "extractionState" : "stale",
@@ -46507,6 +46516,9 @@
           }
         }
       }
+    },
+    "The previous code wasn't accepted. Wait for your authenticator to roll over and enter the new code." : {
+
     },
     "The server will be accessible from other devices on your network. Authentication and TLS are enabled automatically." : {
       "localizations" : {
@@ -50495,6 +50507,12 @@
           }
         }
       }
+    },
+    "Verification Code Rejected" : {
+
+    },
+    "Verification code rejected. The code may be wrong or expired — try a fresh code from your authenticator." : {
+
     },
     "Verification Code Required" : {
       "localizations" : {