feat: identity verification 5.8

[nan-li]

Description

One Line Summary

Add Identity Verification (JWT-based) support to the Android SDK, gating API operations behind server-issued JWTs when enabled.

Details

Motivation

Identity Verification allows app developers to authenticate users with JWTs before the SDK sends operations to the OneSignal backend. This prevents unauthorized API calls by requiring a valid JWT for all user-scoped operations when the feature is enabled server-side via the jwt_required remote param.

Scope

Public API additions:

• OneSignal.login(externalId, jwtBearerToken) — accepts an optional JWT on login
• OneSignal.updateUserJwt(externalId, token) — supply a fresh JWT when the current one expires
• OneSignal.addUserJwtInvalidatedListener(listener) / removeUserJwtInvalidatedListener(listener) — get notified when a JWT is invalidated (e.g. 401 from backend) so the app can provide a new one
• IUserJwtInvalidatedListener / UserJwtInvalidatedEvent — listener interface and event class

Internal changes:

• JwtTokenStore — persistent store mapping externalId → JWT, backed by SharedPreferences
• IdentityVerificationService — reacts to the jwt_required remote param arriving via config HYDRATE; purges anonymous operations when IV is enabled; wires JWT invalidation callbacks
• OperationRepo — gates operation execution on valid JWT when IV is enabled (hasValidJwtIfRequired); handles FAIL_UNAUTHORIZED by invalidating the JWT, re-queuing operations, and notifying the developer; stamps externalId synchronously at enqueue time to avoid race conditions
• LogoutHelper — when IV is enabled, disables the push subscription internally and suppresses the backend login operation (the device-scoped user is local-only)
• ConfigModelStoreListener / ParamsBackendService — reads jwt_required from remote params, defaults to false when absent
• HTTP layer — attaches Authorization: Bearer <jwt> header to requests when IV is enabled
• In-App Messaging — uses alias-based fetch endpoint and includes JWT in IAM backend calls
• Operation executors — propagate externalId to result operations and attach JWT to backend requests

What is NOT affected:

• Apps without Identity Verification enabled behave exactly as before — jwt_required defaults to false and no JWT gating occurs
• Notification display, open handling, push processing, and confirm deliveries are unchanged

Testing

Unit testing

WIP Adding more testing

• OperationRepoTests — added tests for FAIL_UNAUTHORIZED handling (identified user fires handler + retries; anonymous user drops operations), and synchronous externalId stamping before async dispatch
• LoginUserOperationExecutorTests — updated for identity verification parameters
• LogoutHelperTests — covers IV-enabled logout flow
• LoginHelperTests — covers IV-enabled login flow with JWT

Manual testing

Tested with the demo app on an Android emulator (Pixel 7, API 35):

• Login with valid JWT → operations execute normally
• Login with expired JWT → 401 triggers IUserJwtInvalidatedListener, call updateUserJwt → operations resume
• Logout with IV enabled → push subscription disabled, new anonymous user created locally
• App without IV enabled → SDK operates normally, no regression

Affected code checklist

• Notifications
  • Display
  • Open
  • Push Processing
  • Confirm Deliveries
• Outcomes
• Sessions
• In-App Messaging
• REST API requests
• Public API changes

Checklist

Overview

• I have filled out all REQUIRED sections above
• PR does one thing
• Any Public API changes are explained in the PR details and conform to existing APIs

Testing

• I have included test coverage for these changes, or explained why they are not needed
• All automated tests pass, or I explained why that is not possible
• I have personally tested this on my device, or explained why that is not possible

Final pass

• Code is as readable as possible.
• I have reviewed this PR myself, ensuring it meets each checklist item

[nan-li]

@claude re-review

[claude]

Claude finished @nan-li's task in 3m 55s —— View job

---

Re-review: feat/identity_verification_5.8

• Read current state of files related to previous review findings
• Verify fixes for the 4 critical issues flagged
• Look for any remaining or new issues
• Post updated review

---

All four critical issues flagged in the previous review have been addressed. Here's a status breakdown:

Previously Critical — Now Fixed ✅

1. Runtime 401 not firing IUserJwtInvalidatedListener (OperationRepo.kt:292-297)

Fixed correctly. OperationRepo now holds a _jwtInvalidatedHandler: ((String) -> Unit)? that is set in IdentityVerificationService.start():

_operationRepo.setJwtInvalidatedHandler { externalId ->
    _userManager.fireJwtInvalidated(externalId)
}

And in the FAIL_UNAUTHORIZED branch, _jwtInvalidatedHandler?.invoke(externalId) is called after _jwtTokenStore.invalidateJwt(externalId). The queue correctly re-enqueues the operations, and the developer receives the callback to provide a fresh JWT. When updateUserJwt is called, forceExecuteOperations() wakes the queue — the full round trip is wired.

2. Logout race condition — UpdateSubscriptionOperation stamped with null externalId (OperationRepo.kt:165-168)

Fixed correctly. stampExternalId(operation) is now called synchronously in enqueue() before scope.launch { internalEnqueue(...) }. Since SubscriptionModelStoreListener.getUpdateOperation() fires synchronously when isDisabledInternally = true is set — and createAndSwitchToNewUser() has not yet run at that point — _identityModelStore.model.externalId is still the old user's ID when it's captured.

3. JwtTokenStore.ensureLoaded() throws uncaught JSONException (JwtTokenStore.kt:32-42)

Fixed correctly. The JSON parsing is wrapped in try { } catch (e: Exception) and isLoaded = true is placed unconditionally at the end of ensureLoaded(). Corrupted SharedPreferences data is now logged and discarded gracefully instead of causing an infinite throw loop.

4. useIdentityVerification stays null for non-IV apps, permanently blocking the queue (ParamsBackendService.kt:87)

Fixed correctly. The field now defaults to false when jwt_required is absent from the backend response:

useIdentityVerification = responseJson.safeBool("jwt_required") ?: false

Non-IV apps get false after HYDRATE, getNextOps() proceeds, and IdentityVerificationService.onModelReplaced() still calls forceExecuteOperations() to wake the queue.

---

Remaining Observations (non-blocking)

A. _jwtInvalidatedHandler is not @Volatile (OperationRepo.kt:47)

private var _jwtInvalidatedHandler: ((String) -> Unit)? = null

This field is written from IdentityVerificationService.start() (likely the main thread) and read from executeOperations() running on OSOperationRepoScope. In practice this is safe because start() runs before any operations execute, but the JMM doesn't guarantee visibility without @Volatile or a synchronisation point. Worth annotating for correctness. Fix this →

B. Expired JWT at logout time blocks the unsubscribe operation (LogoutHelper.kt)

When IV=true and a 401 has already invalidated the JWT before the user calls logout(), the UpdateSubscriptionOperation (to disable the push subscription) gets a null result from _jwtTokenStore.getJwt(externalId) and is permanently held by hasValidJwtIfRequired. The developer would need to call updateUserJwt with a fresh token to unblock it — but if they're logging out, they likely won't. The backend push subscription stays enabled for the logged-out user until the next cold start (when pruneToExternalIds cleans up the orphaned operation).

This is an edge case (JWT expired + user logs out before providing a refresh) and the overall security posture of the IV feature prevents worse outcomes, but it may be worth documenting or handling explicitly — for example, by skipping the JWT gate for the unsubscribe-on-logout operation. Not blocking the PR.

---

The implementation is solid. All critical issues are resolved and the approach is well-structured. The IdentityVerificationService / OperationRepo / JwtTokenStore responsibilities are cleanly separated.

[nan-li]

@claude re-review

[claude]

Claude finished @nan-li's task in 2m 39s —— View job

---

Re-review: feat/identity_verification_5.8

• Read current state of key files
• Verify fixes for the 2 observations from previous review
• Look for any remaining or new issues
• Post updated review

---

Both remaining observations from the previous re-review have been addressed. The PR is clean.

Previously Non-blocking — Now Fixed ✅

A. _jwtInvalidatedHandler not @Volatile (OperationRepo.kt:47)

Fixed in commit 76dd958. The field is now correctly annotated:

@Volatile
private var _jwtInvalidatedHandler: ((String) -> Unit)? = null

B. Expired JWT at logout blocks the push subscription disable (UpdateSubscriptionOperation.kt:89)

Fixed in commit 130aa16. The first approach (skip in LogoutHelper) was tried and reverted; the final solution is cleaner — it adds Operation.requiresJwt: Boolean = true as an open property on the base class and overrides it in UpdateSubscriptionOperation:

// Operation.kt:69
open val requiresJwt: Boolean get() = true

// UpdateSubscriptionOperation.kt:89
override val requiresJwt: Boolean get() = false

OperationRepo.hasValidJwtIfRequired() short-circuits on !op.requiresJwt, so subscription updates always proceed regardless of JWT state. This is backend-aligned — the subscription endpoint doesn't enforce JWT auth — and the executor still passes the JWT opportunistically when one is available (val jwt = lastOperation.externalId?.let { _jwtTokenStore.getJwt(it) }).

---

Minor Observation (no action needed)

The requiresJwt = false behavior on UpdateSubscriptionOperation has no dedicated test in OperationRepoTests. The behavior is implicitly covered by LogoutHelperTests, but a unit test verifying that an operation with requiresJwt = false executes when hasValidJwtIfRequired would otherwise block could add confidence. Given the simplicity of the change, this is not blocking.

---

The implementation is solid. All six issues identified across both review passes are resolved. The architecture is clean: IdentityVerificationService / OperationRepo / JwtTokenStore responsibilities are well-separated, the requiresJwt flag gives per-operation control over JWT gating, and the developer-facing callback round-trip is fully wired. Good to merge.

[abdulraqeeb33]

we should break it down if its a complex method.

[nan-li]

Yes, I undid the detekt changes and then added them back in the last few commits with reasoning. I actually didn't end up making changes to in-app-messages in detekt.

[abdulraqeeb33]

like i mentioned elsewhere, we need suspend methods for these

[nan-li]

added

[abdulraqeeb33]

Lets try and do a bug bash on this today/tomorrow?

[nan-li]

@claude review

[claude]

The two bugs I flagged in the last pass (IAM rate-limit poisoning and JWT exposure in login() logs) have been fixed in the latest commit — thanks for addressing them. Given the security-sensitive nature of this feature (JWT-based identity gating across 86 files), a final human look before merge is warranted.

Extended reasoning...

Overview

This PR adds Identity Verification (JWT-based authentication gating) to the Android SDK, spanning 86 files including new public API, a new JwtTokenStore, OperationRepo changes, IAM fetch gating, and HttpClient JWT header injection.

Prior Review Rounds

• Rounds 1–2 (late March): 6 bugs found and fixed.
• Round 3 (2026-04-14): 4 new bugs filed as inline comments. The latest commit (82678a5 "Address Claude review bot feedback on IV PR") addresses all of them:
  • ✅ IAM rate-limit poisoning: Guard now checks both and , returning before is set.
  • ✅ JWT logging in / : Both now use .
  • ✅ FAIL_UNAUTHORIZED loop when IV=OFF: Gated on .
  • ✅ JWT in HttpClient logs: Authorization header filtered from logged request properties.
  • 403/401 conflation and stale ops at logout explicitly deferred by author (out of scope / by design).

Security Risks

The PR touches auth-critical paths: JWT storage/retrieval, JWT injection into HTTP headers, FAIL_UNAUTHORIZED error routing, and the public-facing / APIs. No new vulnerabilities found in this pass, but the breadth of the change means a human reviewer should give final sign-off.

Level of Scrutiny

This is production-facing security code that gates API calls behind developer-issued JWTs. The implementation looks correct across the key paths reviewed, but the sheer scope (86 files, new public API surface, threading concerns) means automated review alone is insufficient.

Other Factors

• The LoginHelper pre-HYDRATE logic is sound: the null case falls through to IV=OFF behavior, and IdentityVerificationService cleans up on HYDRATE.
• intentionally omits UNAUTHORIZED handling (requiresJwt=false by design; JWT is passed opportunistically).
• Test infrastructure () correctly gates test suites from the IV hold path.