fix(kotlin-sdk): unmanaged-identity reads return absence + typed SigningKeyUnavailable (split from #4183)

[bfoss765]

Splits the two conflict-free, review-approved slices out of #4183 so they aren't blocked on the
Keystore rework, as suggested by @shumkov in review.

What's included

Unmanaged-identity local reads return absence, not an exception. The FFI's blanket
Option → result conversion reports an identity the wallet does not manage as
PlatformWalletFFIResultCode::NotFound (98), so the Kotlin callers' zero-handle checks were dead and
any local read over an unmanaged identity (e.g. Dashpay.syncState on a contact's identity) threw
instead of returning null/empty.

• Dashpay routes getManagedIdentity through a translateManagedIdentityNotFoundToZero helper:
  contacts() / syncState() / payments() / sendContactRequest() treat "not managed" as
  null / empty / false. ErrorInvalidHandle still propagates — a stale wallet handle never
  masquerades as an unmanaged identity.
• Sweep of the remaining dead == 0L sites flagged in review:
  ManagedPlatformWallet.inMemoryIdentityStates() (one unmanaged id no longer throws through the
  whole listing) and IdentityRegistration.contestedDpnsNames() (the intended "identity is not
  managed by this wallet" error now actually surfaces).
• platform-wallet-ffi: platform_wallet_get_managed_identity keeps the three lookup outcomes
  distinct (handle absent / wallet removed from the manager map → ErrorInvalidHandle; valid wallet
  not managing the id → NotFound), with unit tests pinning both error arms.

Typed SigningKeyUnavailable. The KeystoreSigner "missing key" completion error travels as
free text through Rust and came back as an opaque Generic/WalletOperation failure. It is now
built from a shared MESSAGE_MARKER constant and recognized at the Kotlin boundary as
DashSdkError.PlatformWallet.SigningKeyUnavailable, so hosts can route users to key repair. The
marker is only consulted on the catch-all codes, so dedicated retry-semantics types are never
overridden.

Known limitation, kept deliberately: the discriminator is still message-text-based
(message.contains); moving to a structured code across the FFI boundary is follow-up work in the
parent PR line.

What's NOT included (stays in #4183)

• The Keystore rework: KeySecurityPolicy (AUTH_GATED/DEVICE_BOUND), the keys-alias split and
  legacy-blob migration matrix, decrypt-probing, pending-identity-key state, and their tests.
• The host-visible retarget of native code 98 to a typed PlatformWallet.NotFound (this PR keeps the
  existing 98 → DashSdkError.NotFound mapping, only naming the code via
  PLATFORM_WALLET_NOT_FOUND_CODE).

Testing

• :sdk:compileDebugKotlin and :sdk:testDebugUnitTest (new: ManagedIdentityNotFoundTranslationTest,
  two SigningKeyUnavailable mapping tests; existing 98-mapping tests unchanged and passing).
• cargo test -p platform-wallet-ffi dashpay unit tests, including the two new outcome-classification
  tests.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Improved error reporting when a required signing key is unavailable, with clearer non-retryable guidance.
  • Managed identities that are missing or removed are now handled consistently instead of exposing raw native errors.
  • Wallet handles that are invalid or stale are now distinguished from identities that simply aren’t managed.
  • Identity-related operations and listings continue gracefully when managed identities are no longer available.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 055edfac-fd8d-4971-a6cb-64c150f4ecb6

📥 Commits

Reviewing files that changed from the base of the PR and between 2b3e3fc and 8acb0bd.

📒 Files selected for processing (8)

• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/errors/DashSdkError.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/identity/IdentityRegistration.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/security/KeystoreSigner.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/tokens/Dashpay.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/ManagedPlatformWallet.kt
• packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/errors/DashSdkErrorTest.kt
• packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/tokens/ManagedIdentityNotFoundTranslationTest.kt
• packages/rs-platform-wallet-ffi/src/dashpay.rs

---

📝 Walkthrough

Walkthrough

The PR adds typed missing-signing-key mapping, distinguishes invalid and unmanaged identity lookups in Rust, and centralizes Kotlin translation of managed-identity NotFound errors into zero handles across identity, Dashpay, and wallet flows.

Changes

Platform wallet error handling

Layer / File(s)	Summary
Signing-key error mapping packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/errors/DashSdkError.kt, packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/security/KeystoreSigner.kt, packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/errors/DashSdkErrorTest.kt	KeystoreSigner emits a stable missing-key marker, and matching catch-all native errors map to non-retryable SigningKeyUnavailable while dedicated mappings remain unchanged.
Managed-identity native outcomes packages/rs-platform-wallet-ffi/src/dashpay.rs	Managed-identity lookup classification now separates found, unmanaged, invalid, and stale wallet-handle outcomes, with tests for the resulting native errors.
Managed-identity Kotlin translation packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/tokens/Dashpay.kt, packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/identity/IdentityRegistration.kt, packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/ManagedPlatformWallet.kt, packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/tokens/ManagedIdentityNotFoundTranslationTest.kt	Managed-identity NotFound errors are translated to zero handles for Dashpay, identity registration, and in-memory wallet enumeration; other native errors are rethrown and translation behavior is tested.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

Signing-key error flow

sequenceDiagram
  participant KeystoreSigner
  participant PlatformWalletNative
  participant DashSdkError
  KeystoreSigner->>PlatformWalletNative: completion with missing-key marker
  PlatformWalletNative->>DashSdkError: native code and message
  DashSdkError-->>KeystoreSigner: SigningKeyUnavailable

Loading

Managed-identity lookup flow

sequenceDiagram
  participant KotlinSDK
  participant RustFFI
  participant Dashpay
  KotlinSDK->>RustFFI: get managed identity handle
  RustFFI-->>KotlinSDK: handle, NotFound, or InvalidHandle
  KotlinSDK->>Dashpay: translate NotFound to zero handle
  Dashpay-->>KotlinSDK: managed result or skipped identity

Loading

Possibly related PRs

• dashpay/platform#4183: Updates related DashSdkError signing-key mapping and platform-wallet NotFound handling.

Suggested reviewers: lklimek, llbartekll, zocolini, quantumexplorer, shumkov

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the two main changes: unmanaged-identity reads now return absence and missing signing keys map to SigningKeyUnavailable.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[thepastaclaw]

✅ Final review complete — no blockers (commit 8acb0bd)

[shumkov]

Reviewed the split (two independent passes): exactly the two conflict-free slices, semantically unchanged from the earlier review, with all five getManagedIdentity call paths routed through the translation helper — including the two previously-missed sites (ManagedPlatformWallet.kt:556, IdentityRegistration.kt:100) — and the host-breaking 98-remap correctly left in #4183 with an explicit "not included" note. Stale handles now surface as InvalidHandle instead of masquerading as not-managed, unit-tested at both the FFI path and the classification seam. One note: the changed-packages CI gate skipped the new platform-wallet-ffi unit tests — they've only run locally until a Rust job picks them up. Ready from our side.

[thepastaclaw]

Final validation — Codex + Sonnet

The combined Codex and successful Sonnet reviewer evidence matches the source: the Rust FFI now distinguishes stale wallet handles from valid wallets that do not manage an identity, and all Kotlin managed-identity lookup paths preserve that distinction while returning absence for the latter case. The signing-key mapping shares its marker with the emitting signer and does not override dedicated retry-semantics errors. No concrete in-scope defects were confirmed; the message-based discriminator is an explicitly disclosed and deferred design limitation.

Review provenance

• Codex reviewers: gpt-5.6-sol — general (completed), gpt-5.6-sol — security-auditor (completed), gpt-5.6-sol — ffi-engineer (completed)
• Verifier: gpt-5.6-sol — final-verifier (fallback)
• Sonnet reviewers: claude-sonnet-5 — general (completed), claude-sonnet-5 — security-auditor (completed), claude-sonnet-5 — ffi-engineer (failed), claude-sonnet-5 — ffi-engineer (completed)

[shumkov]

Ran the full test suite on a same-repo ref (dispatch run 29994288801, this head + a v4.1-dev merge): full Rust workspace suite passed, including the two new platform-wallet-ffi tests, and the SwiftDashSDK target compiles against the FFI change (the Swift job's failure there is a pre-existing AppState.swift:185 base error, not this PR).

One ask before merge: cargo fmt — the new get_managed_identity_unknown_wallet_is_invalid_handle test in dashpay.rs fails cargo fmt --check (fork CI never runs the fmt job, so it didn't surface); merging as-is would redden v4.1-dev's formatting check.

[thepastaclaw]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[thepastaclaw]

Final validation — Codex + Sonnet

The incremental change from ce3a17d to 8acb0bd only applies cargo-fmt reflow to an existing unit-test call in packages/rs-platform-wallet-ffi/src/dashpay.rs. It changes no production behavior or test semantics, and cumulative revalidation found no in-scope defects.

Review provenance

• Codex reviewers: gpt-5.6-sol — general (completed), gpt-5.6-sol — security-auditor (completed), gpt-5.6-sol — ffi-engineer (completed)
• Verifier: gpt-5.6-sol — final-verifier (fallback)
• Sonnet reviewers: claude-sonnet-5 — ffi-engineer (completed), claude-sonnet-5 — general (completed), claude-sonnet-5 — security-auditor (completed)