Merge pull request #88 from auths-dev/fn-70

chore: lint sync guard, WitnessConfig versioning, new_unchecked audit, error boundary fixes

Author: bordumb

.github/workflows/ci.yml

@@ -52,6 +52,7 @@ jobs:
           key: ${{ runner.os }}-clippy-${{ hashFiles('**/Cargo.lock') }}
           restore-keys: ${{ runner.os }}-clippy-
       - run: cargo clippy --all-targets --all-features -- -D warnings
+      - run: cargo run -p xtask -- check-clippy-sync
 
   schemas:
     name: Schema validation

.pre-commit-config.yaml

@@ -42,6 +42,13 @@ repos:
         files: (crates/auths-cli/src/|crates/xtask/src/gen_docs|docs/cli/commands/)
         pass_filenames: false
 
+      - id: check-clippy-sync
+        name: cargo xtask check-clippy-sync
+        entry: cargo run --package xtask -- check-clippy-sync
+        language: system
+        files: clippy\.toml$
+        pass_filenames: false
+
       - id: cargo-deny
         name: cargo deny (licenses + bans)
         entry: bash -c 'cargo deny check > .cargo/cargo-deny.log 2>&1; exit $?'

crates/auths-cli/src/commands/device/authorization.rs

@@ -272,7 +272,7 @@ pub fn handle_device(
                 &ctx,
                 &auths_core::ports::clock::SystemClock,
             )
-            .map_err(|e| anyhow!("{e}"))?;
+            .map_err(anyhow::Error::new)?;
 
             display_link_result(&result, &device_did)
         }
@@ -301,7 +301,7 @@ pub fn handle_device(
                 note,
                 &auths_core::ports::clock::SystemClock,
             )
-            .map_err(|e| anyhow!("{e}"))?;
+            .map_err(anyhow::Error::new)?;
 
             display_revoke_result(&device_did, &repo_path)
         }

crates/auths-cli/src/commands/init/mod.rs

@@ -437,7 +437,8 @@ mod tests {
             registry: DEFAULT_REGISTRY_URL.to_string(),
             skip_registration: false,
         };
-        // In test context, stdin is not a TTY
-        assert!(!resolve_interactive(&cmd).unwrap());
+        // Auto-detect returns is_terminal() — result depends on environment
+        let result = resolve_interactive(&cmd).unwrap();
+        assert_eq!(result, std::io::stdin().is_terminal());
     }
 }

crates/auths-cli/src/commands/verify_commit.rs

@@ -919,6 +919,8 @@ mod tests {
 
     #[tokio::test]
     async fn verify_bundle_chain_empty_chain() {
+        #[allow(clippy::disallowed_methods)]
+        // INVARIANT: test-only hardcoded DID and hex string literals
         let bundle = IdentityBundle {
             identity_did: auths_verifier::IdentityDID::new_unchecked("did:keri:test"),
             public_key_hex: auths_verifier::PublicKeyHex::new_unchecked("aa".repeat(32)),
@@ -935,6 +937,8 @@ mod tests {
 
     #[tokio::test]
     async fn verify_bundle_chain_invalid_hex() {
+        #[allow(clippy::disallowed_methods)]
+        // INVARIANT: test-only hardcoded DID, hex, and canonical DID string literals
         let bundle = IdentityBundle {
             identity_did: auths_verifier::IdentityDID::new_unchecked("did:keri:test"),
             public_key_hex: auths_verifier::PublicKeyHex::new_unchecked("not_hex"),

crates/auths-cli/src/errors/renderer.rs

@@ -28,12 +28,13 @@ pub fn render_error(err: &Error, json_mode: bool) {
 }
 
 /// Try to extract `AuthsErrorInfo` from an `anyhow::Error` by downcasting
-/// through all known error types.
+/// through all known error types. Walks the full error chain so that
+/// `.with_context()` wrapping doesn't hide typed errors.
 fn extract_error_info(err: &Error) -> Option<(&str, &str, Option<&str>)> {
     macro_rules! try_downcast {
-        ($err:expr, $($ty:ty),+ $(,)?) => {
+        ($source:expr, $($ty:ty),+ $(,)?) => {
             $(
-                if let Some(e) = $err.downcast_ref::<$ty>() {
+                if let Some(e) = $source.downcast_ref::<$ty>() {
                     let code = AuthsErrorInfo::error_code(e);
                     let msg = format!("{e}");
                     // SAFETY: we leak the String to get a &'static str because
@@ -46,21 +47,23 @@ fn extract_error_info(err: &Error) -> Option<(&str, &str, Option<&str>)> {
         };
     }
 
-    try_downcast!(
-        err,
-        AgentError,
-        AttestationError,
-        SetupError,
-        DeviceError,
-        DeviceExtensionError,
-        RotationError,
-        RegistrationError,
-        McpAuthError,
-        OrgError,
-        ApprovalError,
-        AllowedSignersError,
-        SigningError,
-    );
+    for cause in err.chain() {
+        try_downcast!(
+            cause,
+            AgentError,
+            AttestationError,
+            SetupError,
+            DeviceError,
+            DeviceExtensionError,
+            RotationError,
+            RegistrationError,
+            McpAuthError,
+            OrgError,
+            ApprovalError,
+            AllowedSignersError,
+            SigningError,
+        );
+    }
 
     None
 }
@@ -248,4 +251,11 @@ mod tests {
         assert_eq!(code, "AUTHS-E3001");
         assert!(suggestion.is_some());
     }
+
+    #[test]
+    fn extract_error_info_walks_chain_through_context() {
+        let err: Error = Error::new(AgentError::KeyNotFound).context("operation failed");
+        let (code, _, _) = extract_error_info(&err).unwrap();
+        assert_eq!(code, "AUTHS-E3001");
+    }
 }

crates/auths-core/clippy.toml

@@ -12,6 +12,13 @@ disallowed-methods = [
   { path = "std::env::var", reason = "use EnvironmentConfig abstraction instead of reading env vars directly", allow-invalid = true },
   { path = "uuid::Uuid::new_v4", reason = "Use UuidProvider::new_id() instead. Inject SystemUuidProvider in production and DeterministicUuidProvider in tests." },
 
+  # === DID/newtype construction: prefer parse() for external input ===
+  { path = "auths_verifier::types::IdentityDID::new_unchecked", reason = "Use IdentityDID::parse() for external input. Use #[allow(clippy::disallowed_methods)] with INVARIANT comment for proven-safe paths.", allow-invalid = true },
+  { path = "auths_verifier::types::DeviceDID::new_unchecked", reason = "Use DeviceDID::parse() for external input. Use #[allow(clippy::disallowed_methods)] with INVARIANT comment for proven-safe paths.", allow-invalid = true },
+  { path = "auths_verifier::types::CanonicalDid::new_unchecked", reason = "Use CanonicalDid::parse() for external input. Use #[allow(clippy::disallowed_methods)] with INVARIANT comment for proven-safe paths.", allow-invalid = true },
+  { path = "auths_verifier::core::CommitOid::new_unchecked", reason = "Use CommitOid::parse() for external input. Use #[allow(clippy::disallowed_methods)] with INVARIANT comment for proven-safe paths.", allow-invalid = true },
+  { path = "auths_verifier::core::PublicKeyHex::new_unchecked", reason = "Use PublicKeyHex::parse() for external input. Use #[allow(clippy::disallowed_methods)] with INVARIANT comment for proven-safe paths.", allow-invalid = true },
+
   # === Sans-IO: filesystem ===
   { path = "std::fs::read", reason = "sans-IO crate — use a port trait" },
   { path = "std::fs::read_to_string", reason = "sans-IO crate — use a port trait" },

crates/auths-core/src/api/ffi.rs

@@ -381,6 +381,8 @@ pub unsafe extern "C" fn ffi_import_key(
             }
         };
 
+        #[allow(clippy::disallowed_methods)]
+        // INVARIANT: validated with starts_with("did:") guard above
         let did_string = IdentityDID::new_unchecked(did_str.to_string());
         let alias = KeyAlias::new_unchecked(alias_str);
 

crates/auths-core/src/error.rs

@@ -174,16 +174,27 @@ impl AuthsErrorInfo for AgentError {
                 Some("Run the command again and provide the required input")
             }
             Self::StorageError(_) => Some("Check file permissions and disk space"),
-            // These errors typically don't have actionable suggestions
-            Self::SecurityError(_)
-            | Self::CryptoError(_)
-            | Self::KeyDeserializationError(_)
-            | Self::SigningFailed(_)
-            | Self::Proto(_)
-            | Self::IO(_)
-            | Self::InvalidInput(_)
-            | Self::MutexError(_)
-            | Self::CredentialTooLarge { .. } => None,
+            Self::SecurityError(_) => Some(
+                "Run `auths doctor` to check system keychain access and security configuration",
+            ),
+            Self::CryptoError(_) => {
+                Some("A cryptographic operation failed; check key material with `auths key list`")
+            }
+            Self::KeyDeserializationError(_) => {
+                Some("The stored key is corrupted; re-import with `auths key import`")
+            }
+            Self::SigningFailed(_) => Some(
+                "The signing operation failed; verify your key is accessible with `auths key list`",
+            ),
+            Self::Proto(_) => Some(
+                "A protocol error occurred; check that both sides are running compatible versions",
+            ),
+            Self::IO(_) => Some("Check file permissions and that the filesystem is not read-only"),
+            Self::InvalidInput(_) => Some("Check the command arguments and try again"),
+            Self::MutexError(_) => Some("A concurrency error occurred; restart the operation"),
+            Self::CredentialTooLarge { .. } => Some(
+                "Reduce the credential size or use file-based storage with AUTHS_KEYCHAIN_BACKEND=file",
+            ),
             Self::WeakPassphrase(_) => {
                 Some("Use at least 12 characters with uppercase, lowercase, and a digit or symbol")
             }
@@ -244,7 +255,12 @@ impl AuthsErrorInfo for TrustError {
             Self::Lock(_) => Some("Check file permissions and try again"),
             Self::Io(_) => Some("Check disk space and file permissions"),
             Self::AlreadyExists(_) => Some("Run `auths trust list` to see existing entries"),
-            Self::InvalidData(_) | Self::Serialization(_) => None,
+            Self::InvalidData(_) => {
+                Some("The trust store may be corrupted; delete and re-pin with `auths trust add`")
+            }
+            Self::Serialization(_) => {
+                Some("The trust store data is corrupted; delete and re-pin with `auths trust add`")
+            }
         }
     }
 }

crates/auths-core/src/pairing/error.rs

@@ -55,7 +55,16 @@ impl AuthsErrorInfo for PairingError {
             Self::NoPeerFound => Some("Ensure both devices are on the same network"),
             Self::LanTimeout => Some("Check your network and try again"),
             Self::RelayError(_) => Some("Check your internet connection"),
-            _ => None,
+            Self::Protocol(_) => Some("Ensure both devices are running compatible auths versions"),
+            Self::QrCodeFailed(_) => {
+                Some("QR code generation failed; try `auths device pair --mode relay` instead")
+            }
+            Self::LocalServerError(_) => {
+                Some("The local pairing server failed to start; check that the port is available")
+            }
+            Self::MdnsError(_) => {
+                Some("mDNS discovery failed; try `auths device pair --mode relay` instead")
+            }
         }
     }
 }