fix(wallets): preserve OTP validation failure reason instead of collapsing into generic error

[devin-ai-integration]

Description

During wallet recovery, when complete-onboarding returns an OTP validation failure, the error gets collapsed into a generic Error that surfaces as "Crossmint signer returned an internal error" in consumer apps. The SDK loses the underlying auth/OTP failure context at two points:

1. verifyOtp creates a plain Error(response.error) — no typed error class, no error code from the TEE response
2. recover() treats OTP failures as unknown errors (falls to the generic else branch), which destructively deletes the device key

This PR:

• Adds OtpValidationError (extends Error) with an optional code field for the TEE error code
• verifyOtp and sendMessageWithOtp now throw OtpValidationError instead of generic Error, forwarding response.code
• recover() handles OtpValidationError like AuthRejectedError: preserves the local device key so the user can retry the OTP flow without re-registering
• Exports OtpValidationError from @crossmint/wallets-sdk so consumers can instanceof-check and surface the real reason

Error flow before:

TEE: {status:"error", error:"An internal error occurred"} 
→ verifyOtp: throw new Error("An internal error occurred")
→ recover catch: generic else → deleteKey + rethrow
→ consumer: "Crossmint signer returned an internal error"

Error flow after:

TEE: {status:"error", error:"An internal error occurred", code:"..."}
→ verifyOtp: throw new OtpValidationError("An internal error occurred", code)
→ recover catch: OtpValidationError → keep key + rethrow
→ consumer: can catch OtpValidationError, access .message and .code

Test plan

• Added unit test preserves local key and rethrow when addSigner fails with OtpValidationError — verifies deleteKey is NOT called and OtpValidationError propagates
• Existing AuthRejectedError test still passes (no regression)
• Full @crossmint/wallets-sdk test suite passes (337 tests)

Package updates

• @crossmint/wallets-sdk — patch (changeset added)

Link to Devin session: https://crossmint.devinenterprise.com/sessions/7bd8230602444a8a94498384e0aac02d
Requested by: @xmint-guille

[devin-ai-integration]

Original prompt from Guille

@skills:cse spotpay reported the following, investigate when this could happen and how should we improve our error client side:
During wallet recovery, complete-onboarding returns OTP validation failed, but the app surfaces it as:
"Crossmint signer returned an internal error"

This happens in the wallet recovery/addSigner path, likely when registering the device signer after auth is required. Logs show:

• wallet.recover.start
• complete-onboarding request
• complete-onboarding: OTP validation failed
• wallet.addSigner threw
• wallet.recover threw
• Error in verifyOtp
• Crossmint signer returned an internal error

The SDK should preserve the underlying auth/OTP failure reason instead of collapsing it into an internal signer error. Also distinguish true user cancellation from failed OTP / recovery errors.
ATTACHMENT:"https://crossmint.devinenterprise.com/attachments/76cc8351-35a7-4370-9a64-206aa1191469/CleanShot+2026-06-02+at+14.08.27%402x.png"

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[changeset-bot]

🦋 Changeset detected

Latest commit: 144f8fe

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@crossmint/wallets-sdk	Patch
@crossmint/wallets-quickstart-devkit	Patch
@crossmint/wallets-playground-react	Patch
@crossmint/client-sdk-react-base	Patch
@crossmint/client-sdk-react-native-ui	Patch
@crossmint/client-sdk-react-ui	Patch
@crossmint/wallets-playground-expo	Patch
@crossmint/auth-ssr-nextjs-demo	Patch
@crossmint/client-sdk-nextjs-starter	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[greptile-apps]

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
packages/wallets/src/signers/non-custodial/ncs-signer.ts:332
The `sendMessageWithOtp` error path already guards against an absent `response.error` field with `response.error || "Failed to initiate OTP process."`, but `verifyOtp` does not apply the same guard. When the TEE returns `{status:"error"}` without an `error` field, `errorMessage` becomes `undefined`, and `OtpValidationError` ends up with the literal string `"undefined"` as its message — which would be a confusing surface to a consumer.

```suggestion
        const errorMessage = response?.status === "error" ? (response.error || "Failed to validate encrypted OTP") : "Failed to validate encrypted OTP";
```

_{Reviews (1): Last reviewed commit: "chore: add changeset for OtpValidationEr..." | Re-trigger Greptile}

[greptile-apps]

_{Reviews (2): Last reviewed commit: "fix: guard against undefined response.er..." | Re-trigger Greptile}

[greptile-apps]

_{Reviews (3): Last reviewed commit: "fix: remove unnecessary parentheses to s..." | Re-trigger Greptile}