feat(iv): foundation: gates singleton, JWT token store, feature flag entry (1/6)

[nan-li]

Description

One Line Summary

First of five PRs against the Identity Verification integration branch — lands foundation primitives (IdentityVerificationGates singleton, JwtTokenStore, FeatureFlag.IDENTITY_VERIFICATION entry) with no consumer wiring or public API yet.

Details

Motivation

IV is gated behind two nested conditions:

• SDK-side rollout switch — FeatureFlag.IDENTITY_VERIFICATION controlled via Turbine.
• Customer config — jwt_required remote param from the backend.

Post-release rollout strategy: ship with feature flag OFF; customers with jwt_required=true get IV via the customer-config override; progressively flip the feature flag ON for remaining customers to validate structural changes independent of IV activation.

Scope

All additions are inert at runtime — nothing consumes the gates or the JWT store yet. Subsequent PRs wire them in:

• PR 2 - 3 — OperationRepo IV gating, pre-HYDRATE deferral, anon-op purge race fix.
• PR 4 — HTTP Authorization header + executor JWT integration.
• PR 5 — Public API (login(externalId, jwt), updateUserJwt, listeners) + replay.
• PR 6 — Logout + IAM integration + RYW plumbing.

What lands in this PR:

New files:

• IdentityVerificationGates.kt — singleton object mirroring ThreadingMode. Volatile newCodePathsRun (= featureFlag || jwtRequired == REQUIRED) and ivBehaviorActive (= jwtRequired == REQUIRED). The two gates differ on purpose: customer config must be honored even when the feature flag is off, otherwise a kill-switch flip would break customers who've already enabled IV server-side.
• JwtRequirement.kt — tri-state enum (UNKNOWN / NOT_REQUIRED / REQUIRED) for ConfigModel.useIdentityVerification, replacing the original Boolean?. Explicit about pre-HYDRATE; visually distinct from FeatureFlag.IDENTITY_VERIFICATION.
• JwtTokenStore.kt — SharedPreferences-backed externalId → JWT map. Multi-user so ops queued under a previous user can still resolve their JWT at execution time. Storage is unconditional; usage is gated on IdentityVerificationGates.ivBehaviorActive.
• IJwtUpdateListener.kt — pure wake-up notification (onJwtUpdated(externalId) with no payload). Subscribers must re-read getJwt(externalId); matches the ModelStore convention and avoids stale-ordering hazards when multiple threads write.

Modified files:

• FeatureFlag.kt — added IDENTITY_VERIFICATION("identity_verification", IMMEDIATE). IMMEDIATE because a Turbine kill-switch should take effect within a foreground-poll cycle rather than wait for a cold start, and because the jwt_required side of the gate is already live-updating via HYDRATE — keeping both inputs symmetric.
• FeatureManager.kt — applySideEffects now has an IDENTITY_VERIFICATION branch pushing both into IdentityVerificationGates.
• ConfigModel.kt — useIdentityVerification type changed to JwtRequirement (internal property because the enum is internal). Backing storage is unchanged (still a nullable boolean), so no cache migration needed.
• IPreferencesService.kt — added PREFS_OS_JWT_TOKENS key.
• CoreModule.kt — registered JwtTokenStore in DI.

Gate-access pattern: single-tier. Consumers read IdentityVerificationGates.newCodePathsRun / .ivBehaviorActive directly. Pre-init the volatile fields default to false (safe fallback). Post-init they're populated by FeatureManager.init → refreshEnabledFeatures → applySideEffects, and refreshed on every HYDRATE because IDENTITY_VERIFICATION is IMMEDIATE.

IdentityVerificationService is NOT in this PR — moves to PR 2 where its HYDRATE handler has real work (anon-op purge, queue wake). The IMMEDIATE activation mode means FeatureManager.applySideEffects refreshes the gates on every HYDRATE without needing a separate listener in PR 1.

Testing

Unit testing

• IdentityVerificationGatesTests — 9 tests covering the full gate matrix including the ERROR STATE row (feature flag off, jwt_required=REQUIRED → customer config wins).
• JwtTokenStoreTests — 17 tests: put/get/invalidate/prune, persistence round-trip, listener notifications (fire on change, no-op on no-change, fire on invalidation/prune), malformed JSON recovery.
• FeatureManagerTests — added IV coverage: flag-off baseline, flag-on newCodePathsRun, ERROR STATE row, full IV, HYDRATE propagation, IMMEDIATE mid-session flip.
• FeatureFlagTests — key and activation-mode assertions for IDENTITY_VERIFICATION.
• stubConfigModel helper updated to stub useIdentityVerification with JwtRequirement.UNKNOWN by default.

Manual testing

Not applicable — no runtime behavior change in this PR. All new code is unreferenced by consumers.

Affected code checklist

• Notifications
• 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 — lands IV foundation primitives only
• Any Public API changes are explained in the PR details and conform to existing APIs (none in this PR)

Testing

• I have included test coverage for these changes
• All automated tests pass locally (pre-existing SDKInitTests failures on the integration branch are unrelated)
• Manual testing is not applicable — no runtime behavior change

Final pass

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

[nan-li]

@claude review

[claude]

Prior race-condition concern was addressed (payload dropped from IJwtUpdateListener); only a nit remains, but deferring since this lands persistent JWT storage and the IV gate primitives that subsequent PRs will build on.

Extended reasoning...

Overview

This is a foundation PR for the Identity Verification (IV) initiative across the OneSignal Android SDK. It adds: FeatureFlag.IDENTITY_VERIFICATION (IMMEDIATE activation), an IdentityVerificationGates singleton tracking newCodePathsRun/ivBehaviorActive, a SharedPreferences-backed JwtTokenStore (externalId → JWT) with an IJwtUpdateListener event interface, a JwtRequirement enum that replaces ConfigModel.useIdentityVerification: Boolean so callers can distinguish pre-HYDRATE from explicit false, and DI wiring in CoreModule. There is no consumer wiring or public API change in this PR — those are deferred to follow-on PRs.

Security risks

The PR introduces persistent storage of JWT tokens in unencrypted SharedPreferences (PREFS_OS_JWT_TOKENS). On most modern Android devices file-based encryption protects this at rest, but tokens are still readable by any process running as the app's UID (e.g. via root or a backup). This is consistent with how the SDK persists other identifiers, but is worth flagging for human review since this is the first JWT-bearing material the SDK persists. No injection / auth-bypass / TOCTOU concerns in the storage logic itself; ensureLoaded recovers gracefully from corrupt JSON and tests cover that path.

Level of scrutiny

Higher than a typical config tweak. The PR is foundation code for an auth-adjacent feature (JWT signing of SDK requests), introduces a new persistence surface, and changes the type of an existing ConfigModel property that is read across the codebase. Even though it lands no consumer wiring, the contracts here (gate semantics, event interface, persistence format) constrain the design of the four follow-on PRs in the series. That makes it worth a human pass before merge.

Other factors

Test coverage is thorough: the gate-state matrix (including the documented ERROR STATE row where jwt_required overrides a false feature flag), JWT store put/get/invalidate/prune, listener broadcast, and FeatureManager propagation on init and HYDRATE are all covered. The author addressed my prior race-condition concern by taking option 1 from the suggestion (commit ae498ac dropped the JWT payload from IJwtUpdateListener.onJwtUpdated so subscribers must re-query getJwt, and added a doc comment to that effect on the interface) and additionally refactored Boolean? to a three-state JwtRequirement enum (commit b02645d) for clearer pre-HYDRATE handling. The only new finding from this round is a nit about preserving the Throwable stack trace in JwtTokenStore.ensureLoaded — non-blocking. Deferring to nan-li for the human pass they requested.

[claude]

Previous structural concern about event payload ordering was addressed by dropping the payload from IJwtUpdateListener; remaining items are nits.

Extended reasoning...

Overview

Foundation PR (1 of 5) for Identity Verification: adds IdentityVerificationGates singleton, JwtTokenStore, JwtRequirement enum, IJwtUpdateListener, a new IDENTITY_VERIFICATION FeatureFlag entry, and threads ConfigModel through FeatureManager.applySideEffects. ConfigModel.useIdentityVerification changes from Boolean to the new enum but backs the same nullable-boolean storage (no cache migration). Test coverage is thorough (gate matrix including the ERROR STATE row, JwtTokenStore put/get/invalidate/prune/persistence/listener behaviors, FeatureManager IV wiring including HYDRATE propagation and the mid-session IMMEDIATE flip).

Security risks

Low for this PR in isolation — nothing reads the gates or the JWT store yet, so there is no runtime behavior change. The JWT store persists tokens in SharedPreferences under a new key; this matches how other sensitive config is stored in the SDK and the actual auth/HTTP integration is deferred to PR 3. No injection or auth-bypass surface introduced here.

Level of scrutiny

Moderate. It is foundation code for a security feature, but it is intentionally inert — the real scrutiny load lands in PRs 2–5 when consumers wire in. The one design decision worth calling out (payload-less event with a re-query contract) was already surfaced in my prior review and the author adopted it, which is visible in the current IJwtUpdateListener signature and its documentation comment.

Other factors

• My earlier concern about event-ordering in JwtTokenStore was addressed by dropping the JWT payload from onJwtUpdated and explicitly documenting the re-query contract. That was the substantive issue.
• Outstanding items are nits: (a) ensureLoaded logs e.message rather than forwarding the throwable to Logging.warn; (b) the two @Volatile writes in IdentityVerificationGates.update are sequential so a reader can transiently observe (newCodePathsRun=false, ivBehaviorActive=true) during a (true,true)→(false,false) transition, violating the file-level invariant. Neither affects runtime today since there are no consumers, and both are trivially fixable before PR 2 lands.
• Test coverage is strong and the PR scope is tight.