feat(kotlin-sdk): DashPay invitations — create, claim, reclaim, persistence (DIP-13)

[shumkov]

Issue being fixed or feature implemented

Ports the shipped iOS DashPay invitation feature (DIP-13 sub-feature 3', PR #4041) to the Kotlin SDK and KotlinExampleApp — the last DashPay gap left out of the K1–K3 migration. Android was deliberately fail-closed (on_persist_invitations_fn: None), refusing invitation creation rather than risk the voucher-key-reuse defect class (55937e1).

Spec + owner decisions + funded-e2e evidence: docs/dashpay/KOTLIN_INVITATIONS_SPEC.md.

What was done?

Zero shared-Rust changes — all invitation logic stays in rs-platform-wallet; the port is bindings + persistence + UI:

• Persistence spine: InvitationEntity (field-exact with PersistentInvitation.swift, no secret column) + DAO; Room v7→v8 additive migration; per-row bridge slots + JNI trampoline; CAPABILITY_INVITATIONS attested in the same commit that wires the path. Hardening: the address-pool persist no longer silently skips a missing IdentityInvitation account row — it creates it or fails the round so Rust aborts before broadcasting (red→green demonstrated); JNI↔Kotlin descriptor lockstep is pinned by an instrumented test resolving every bridge slot up front.
• Bindings + wrappers: parseInvitation / createInvitation / claimInvitation JNI exports + Kotlin wrappers (InvitationPreview, 6-key claim set); reclaim forwards consumeInvitationVoucher through the existing resume/top-up bindings (Rust core's authorized_invitation_reclaim remains the enforcement, matching iOS's trust model) with two new outpoint-taking reclaim wrappers — the only true-passing call sites.
• App UI: InvitationsScreen / CreateInvitationSheet / ClaimInvitationSheet / ReclaimInvitationSheet, testTags = iOS accessibility identifiers verbatim; deep-link intent-filters with walletless parking; the verbatim reclaim-outcome classifier + reclaimInFlight marker discipline; bearer-secret hygiene (no logging, text-only share, sensitive + auto-cleared clipboard).
• Independent review folded: a cross-model review produced 17 findings; all confirmed ones fixed (active-identity/wallet binding, deep-link navigation + one-shot intents, app-scope clipboard clear, busy-gated dismissal, fail-closed DAO marker writes, QR-scan claim path, a stale red Rust test). Deferrals with rationale in spec §9.
• QA contract rows DP-12..DP-19 (KotlinExampleApp/TEST_PLAN.md), parity manifest (kotlin: supported/partial) + regenerated PARITY_SUMMARY.md.

How Has This Been Tested?

• JVM suites green (handler round-trips incl. the round-failure red→green, classifier outcome matrix, wrapper seams, InvitationPreview contract).
• cargo test -p rs-unified-sdk-jni --lib 37/37; clippy clean.
• Instrumented on the CI-image emulator: 32/32 — Room MIGRATION_7_8 + full v1→v8 chain, the descriptor-resolution gate, FFI smoke.
• Funded testnet e2e on an arm64 emulator (evidence in spec §7): create (0.03, InstantSend-locked, row persisted) → claim (new identity, 2.82B credits, no L1 on the claimer side) → already-consumed race classified live ("This invitation was already claimed.", row → Claimed) → an IS-timeout create still persisted + reclaimable → reclaim-as-top-up (+2.92B credits on-chain, row → Reclaimed) → malformed-link rejection. DP-14 (two-wallet contact bootstrap) and DP-18 (reclaim-as-register) remain manual funded gates, as on iOS.

Breaking Changes

None.

Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated relevant unit/integration/functional/e2e tests
• I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
• I have made corresponding changes to the documentation if needed

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 3d70145a-ac21-4845-aa68-c17d8a2ef02f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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]

⛔ Blockers found — Sonnet deferred (commit f474ab1)
Canonical validated blockers: 3

[thepastaclaw]

Preliminary review — Codex only

The JNI ownership, persistence callbacks, reclaim authorization forwarding, and fail-closed storage path are sound. Three blocking issues remain: the claim can submit a URI different from its displayed preview, QR scans pass the bearer credential through restorable saved state, and invitation registrations can reuse identity-key slots held by registrations already in flight; two additional security and timestamp-width improvements are also warranted.

Source: reviewers codex/general=gpt-5.6-sol(completed); codex/security-auditor=gpt-5.6-sol(completed); codex/ffi-engineer=gpt-5.6-sol(completed); verifier=codex/verifier=gpt-5.6-sol(completed); coordinator=openclaw-agent/cliproxy/gpt-5.6-sol(orchestration-only).

Validated blockers were found in the Codex precheck. Sonnet is deferred until a fresh Codex revalidation clears the blocker gate.

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 — verifier
• Sonnet: not run (deferred by blocker gate)

🔴 3 blocking | 🟡 2 suggestion(s)

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/ui/dashpay/ClaimInvitationSheet.kt`:
- [BLOCKING] packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/ui/dashpay/ClaimInvitationSheet.kt:107-113: Submit only the URI associated with the displayed preview
  Changing `uriText` does not immediately invalidate `preview`; the replacement is parsed later by `LaunchedEffect`. During that interval, `canClaim` remains true based on the previous valid preview, but `claim()` snapshots the newly entered URI. The user can therefore approve one displayed inviter and irreversibly claim a different credential, and the post-claim contact prompt can also use metadata from the stale preview. Store the trimmed URI with each completed preview, require that pair to match before enabling Claim, and snapshot both values together when submission starts.
- [BLOCKING] packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/ui/dashpay/ClaimInvitationSheet.kt:120-124: Reserve identity HD slots across every registration flow
  The next identity index is derived only from identities already committed to Room. It excludes slots held by the application-scoped `RegistrationCoordinator` in `PreparingKeys`, `InFlight`, or `Unconfirmed`, and the chosen index is not atomically reserved before keys are derived. A concurrent normal registration, claim, or reclaim-register can therefore use the same wallet/index and produce identical ECDSA public-key hashes for different identities. Platform's identity-create state validation treats those hashes as duplicates and applies a `PartiallyUseAssetLockAction` charging the unique-key penalty plus processing fees, so the invitation voucher can be partially consumed without creating the identity; retries continue selecting the absent Room slot. The same allocation occurs in `ReclaimInvitationSheet.kt:143-145`. Introduce an application-scoped per-wallet slot allocator shared by all registration paths and reserve the index before key derivation.

In `packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/ui/dashpay/DashPayTabScreen.kt`:
- [BLOCKING] packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/ui/dashpay/DashPayTabScreen.kt:140-147: Keep scanned invitation URIs out of SavedStateHandle
  The generic scanner writes its raw result into `SavedStateHandle`, and this invitation path consumes the plaintext bearer URI from that channel. Values in `SavedStateHandle` participate in saved-instance-state restoration, so a state snapshot taken after delivery and before the collector clears the key can retain the voucher WIF across activity or process recreation. This violates the feature's normative rule that invitation URIs remain in memory and are never persisted. Deliver invitation scan results through a transient, non-saveable one-shot registry or application-scoped event instead.

In `packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/ui/dashpay/CreateInvitationSheet.kt`:
- [SUGGESTION] packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/ui/dashpay/CreateInvitationSheet.kt:203-214: Protect bearer invitation screens with FLAG_SECURE
  The result screen renders a QR containing the plaintext voucher WIF without activating the app's existing `LocalSecureScreen` protection. Android can consequently expose the credential through screenshots, screen recordings, MediaProjection, or task snapshots, allowing anyone with the image to claim the voucher. Hold `FLAG_SECURE` while the created-link QR is visible and while `ClaimInvitationSheet` contains a nonblank invitation URI, then release it on disposal, following the seed and key-reveal screen pattern.

In `packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/tokens/Dashpay.kt`:
- [SUGGESTION] packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/tokens/Dashpay.kt:434: Carry u32 invitation timestamps without signed narrowing
  The Kotlin-to-JNI path narrows Unix seconds to a signed 32-bit `Int`, while the shared C API intentionally accepts `u32`. At Unix second 2147483648, the default becomes negative and JNI rejects every invitation creation even though the C API remains valid through 2106. The persistence callback independently casts `expiry_unix` and `created_at_secs` from `u32` to `jint`, and `InvitationEntity` stores both as `Int`; the roughly 24-hour expiry begins overflowing shortly before the creation-time cutoff, producing negative values and incorrect display and ordering. Use Kotlin `Long` and JNI `jlong` throughout, validate the range `1..u32::MAX` before Rust casts, update the callback descriptor and descriptor-resolution test, and store both Room fields as `Long`.

[thepastaclaw]

🔴 Blocking: Submit only the URI associated with the displayed preview

Changing uriText does not immediately invalidate preview; the replacement is parsed later by LaunchedEffect. During that interval, canClaim remains true based on the previous valid preview, but claim() snapshots the newly entered URI. The user can therefore approve one displayed inviter and irreversibly claim a different credential, and the post-claim contact prompt can also use metadata from the stale preview. Store the trimmed URI with each completed preview, require that pair to match before enabling Claim, and snapshot both values together when submission starts.

_{source: ['codex']}

[thepastaclaw]

🔴 Blocking: Keep scanned invitation URIs out of SavedStateHandle

The generic scanner writes its raw result into SavedStateHandle, and this invitation path consumes the plaintext bearer URI from that channel. Values in SavedStateHandle participate in saved-instance-state restoration, so a state snapshot taken after delivery and before the collector clears the key can retain the voucher WIF across activity or process recreation. This violates the feature's normative rule that invitation URIs remain in memory and are never persisted. Deliver invitation scan results through a transient, non-saveable one-shot registry or application-scoped event instead.

_{source: ['codex']}

[thepastaclaw]

🔴 Blocking: Reserve identity HD slots across every registration flow

The next identity index is derived only from identities already committed to Room. It excludes slots held by the application-scoped RegistrationCoordinator in PreparingKeys, InFlight, or Unconfirmed, and the chosen index is not atomically reserved before keys are derived. A concurrent normal registration, claim, or reclaim-register can therefore use the same wallet/index and produce identical ECDSA public-key hashes for different identities. Platform's identity-create state validation treats those hashes as duplicates and applies a PartiallyUseAssetLockAction charging the unique-key penalty plus processing fees, so the invitation voucher can be partially consumed without creating the identity; retries continue selecting the absent Room slot. The same allocation occurs in ReclaimInvitationSheet.kt:143-145. Introduce an application-scoped per-wallet slot allocator shared by all registration paths and reserve the index before key derivation.

_{source: ['codex']}

[thepastaclaw]

🟡 Suggestion: Protect bearer invitation screens with FLAG_SECURE

The result screen renders a QR containing the plaintext voucher WIF without activating the app's existing LocalSecureScreen protection. Android can consequently expose the credential through screenshots, screen recordings, MediaProjection, or task snapshots, allowing anyone with the image to claim the voucher. Hold FLAG_SECURE while the created-link QR is visible and while ClaimInvitationSheet contains a nonblank invitation URI, then release it on disposal, following the seed and key-reveal screen pattern.

_{source: ['codex']}

[thepastaclaw]

🟡 Suggestion: Carry u32 invitation timestamps without signed narrowing

The Kotlin-to-JNI path narrows Unix seconds to a signed 32-bit Int, while the shared C API intentionally accepts u32. At Unix second 2147483648, the default becomes negative and JNI rejects every invitation creation even though the C API remains valid through 2106. The persistence callback independently casts expiry_unix and created_at_secs from u32 to jint, and InvitationEntity stores both as Int; the roughly 24-hour expiry begins overflowing shortly before the creation-time cutoff, producing negative values and incorrect display and ordering. Use Kotlin Long and JNI jlong throughout, validate the range 1..u32::MAX before Rust casts, update the callback descriptor and descriptor-resolution test, and store both Room fields as Long.

_{source: ['codex']}