macOS 27.0.1: diagnosing SecItemCopyMatching errSecAuthFailed (-25293)

On macOS 27.0.1, SecItemCopyMatching returns -25293 (errSecAuthFailed) when a native app reads an existing login keychain item. We have verified that the app signature matches and that the user has added the app to the list of allowed applications. This occurs with user interaction disabled, and execution stops before connecting to the mail server.

Is there an officially recommended diagnostic method to distinguish whether the cause is app authorization, the execution session, or the internal state of the keychain, without reading secret information, changing permissions, or unlocking the keychain?

There isn't a single public API that tells you which authorization check caused -25293. Apple defines errSecAuthFailed broadly as an authorization and/or authentication failure, so the code alone can't distinguish a bad ACL, an authentication requirement, or keychain state.

Without changing access or reading the secret, I'd first record the exact query's nonsecret fields (class, service, account, access group, synchronizable and data-protection-keychain flags) and the returned OSStatus. Then compare the item's access group with the signed app's keychain entitlements, and confirm the query is targeting the same keychain type that contains the item. On macOS the legacy file-based keychain and the data-protection keychain behave differently; Apple's TN3137 explains how to tell which API path you're using.

If the query and entitlements line up, capture a minimal reproduction and a sysdiagnose while the failure is happening for Apple. A user-visible Keychain Access prompt or a manual unlock may change the state you're trying to diagnose, so I wouldn't use that as the first test if the goal is to observe the failure unchanged.

References: Security Framework result codes, TN3137: On Mac keychain APIs and implementations, keychain access groups.