Server-backed highlights go live: auth hardening + delete-flash fix

[cameronapak]

Summary

Server-backed BibleReader highlights go live: the dark-launch flag flips on after a final round of auth hardening, a fix for successful deletes being misread as failures, and Swift-parity UX corrections. Last PR of the YPE-1034 stack (#283 → #285 → #286 → this one); the consolidated changelog announces the launch and the removal of the accidentally shipped localStorage-only highlights.

Changes

1. Highlights are enabled by default (HIGHLIGHTS_LIVE on) — signed-in readers' highlights persist to their YouVersion account; six stacked changesets are consolidated into one launch changelog.
2. Removing a highlight no longer flashes back before disappearing — the core ApiClient treated empty-body 2xx JSON responses (the real DELETE shape) as failures, so the machine reverted the successful removal; regression tests now drive the real client through a stubbed fetch.
3. A data-exchange grant only applies to the user who initiated it — initiator recorded at redirect, read-and-cleared at callback, any mismatch fails closed; signIn also clears stale permission stashes so an abandoned flow can't leak grants across users.
4. A resumed pending write that fails 401/403 re-prompts for permission instead of silently reverting the reader's tap.
5. Sign-in matches the Swift SDK: appName / signInPromptMessage props, Platform wordmark, comma-joined requested_permissions wire format, and a permission cache seeded from token scope so a highlight tap doesn't re-prompt right after OAuth.
6. Dark mode matches the Swift SDK: highlight fills render at 0.3 opacity (1.0 in light mode) and verse numbers paint white over dark-mode fills; the active swatch shows a checkmark instead of an X.
7. Hardening and cleanup: xstate pinned to exactly 5.32.4 (supply-chain cooldown), review findings across all three packages (color row gated on interactivity, stable serverColors/refetch identities, shared useApiClient), the logo's accessible label is a required localized prop, the pending-permissions stash stores string[], and personal workflow notes are stripped from AGENTS.md.

Start here: change 3 — auth-boundary logic; the fail-closed path is the part worth adversarial review.

Test plan

• pnpm build && pnpm typecheck && pnpm lint && pnpm test: all green (972 tests — core 349 / hooks 288 / ui 335)
• Vapor regression suite fails on the reverted fix, passes with it (fetch-stub end-to-end through the real client, machine, and adapter)
• Storybook integration tests run in CI

Needs manual check: remove a highlight in the signed-in vite demo and confirm it vanishes with no flash — the fix is test-covered, but the live confirmation was blocked by a signed-out demo session.

Greptile Summary

This PR hardens the highlights feature for production (HIGHLIGHTS_LIVE flipped to true) with four targeted fixes on top of the restored stack from #288: cross-user grant isolation in the data-exchange callback (fail-closed via initiator binding), 401/403 re-prompt for resumed pending writes, several code-quality cleanups (reference-stable serverColors, shared useApiClient, stable refetch identity via fetchFnRef), and an xstate rollback from 5.32.5 → 5.32.4.

• Change 1 + 6 (auth boundary): The data-exchange grant is now state-bound to the initiating user: saveDataExchangeInitiator() is called before the token mint, the callback reads-and-clears it atomically, and a user or initiator mismatch degrades to failure. signIn also clears any stale stash and initiator from a prior abandoned flow so cross-user leakage is prevented on both code paths.
• Change 2 (resume re-prompt): The reprompt field was removed from WriteOp; now any apply op (user-initiated or resume-applied) re-stashes and re-prompts on 401/403, while removes only invalidate the cache — fixing the silent intent-drop that existed for pending resumes.
• Change 3 (cleanups): serverColors is reference-stable via a useRef equality guard, useApiClient consolidates client construction across four hooks, and refetch identity is stabilized via a fetchFnRef pattern in useApiData (explicit deps array still drives re-fetches, so no behavior regression).

Confidence Score: 5/5

The auth-boundary hardening is well-implemented and fail-closed; no grant cross-user leakage paths remain.

The core change — binding the data-exchange grant to the initiating user via a read-and-cleared stash — is correctly implemented: the initiator is saved before the async token mint, consumed atomically at callback entry, and any mismatch (different user, missing initiator) degrades to failure rather than silently saving the grant. The stash is also state-bound so a pre-code hop from a different OAuth flow cannot contribute grants. The signIn path correctly purges any prior stash and initiator before starting a new flow. The resume-write re-prompt fix and the signedOut guard in the permission-dialog state are both straightforward and well-tested. The only non-blocking note is that the OIDC_SCOPES denylist used when seeding the permission cache from token scope is a hardcoded set that could grow stale if the auth server adds new standard scopes.

packages/core/src/Users.ts — the OIDC_SCOPES denylist approach for filtering token scope before storing in the permission cache.

Important Files Changed

Filename	Overview
packages/core/src/Users.ts	Adds cross-user grant isolation via state-bound stash and initiator binding; the fail-closed logic is solid. Minor: OIDC_SCOPES denylist could grow stale.
packages/core/src/data-exchange.ts	Initiator is read-and-cleared atomically before the grant check; user-mismatch and missing-initiator both degrade correctly to failure. URL cleanup fires regardless of mismatch.
packages/ui/src/components/bible-reader-highlights-machine.ts	Removes the reprompt field; all apply ops (user-initiated and resume) now correctly re-stash + re-prompt on 401/403. The new signedOut always-guard cleanly drops pending state when the user signs out while the permission dialog is open.
packages/hooks/src/useApiData.ts	fetchFnRef pattern correctly stabilizes refetch identity without breaking re-fetches — the explicit deps array (not fetchFn identity) still drives the useEffect trigger.
packages/hooks/src/internal/useApiClient.ts	New shared hook DRYs up ApiClient construction across four consumer hooks; optional: true variant for useHighlightAuthActions is cleanly typed with overloads.
packages/core/src/SignInWithYouVersionPKCE.ts	Permissions wire format changed from repeated requested_permissions[] to single comma-joined requested_permissions (Swift/Kotlin parity). Tests updated to match.
packages/ui/src/components/use-bible-reader-highlights.ts	serverColors now reference-stable via equality guard; highlightsInteractive exposed to prevent dead color-swatch rows in copy/share-only integrations.
packages/ui/src/lib/feature-flags.ts	HIGHLIGHTS_LIVE flipped to true, enabling highlights for all integrators.
packages/ui/src/components/verse.tsx	Theme-aware highlight fill opacity added (full strength light, 0.3 dark) with white verse-number labels in dark mode — mirrors Swift SDK UX baseline.

Sequence Diagram

sequenceDiagram
    participant User
    participant SDK as SDK
    participant Config as Config
    participant Server as Server

    Note over User,Server: Data-exchange grant flow with initiator binding
    User->>SDK: startDataExchange()
    SDK->>Config: saveDataExchangeInitiator(currentUserId)
    SDK->>Server: updateToken([highlights])
    Server-->>SDK: exchange token
    SDK->>User: redirect to dataExchangeUrl

    Note over User,Server: Page navigates — redirect returns
    Server->>SDK: callback URL with granted status
    SDK->>Config: read + clear dataExchangeInitiator
    SDK->>Config: read currentUserId

    alt initiator equals currentUserId
        SDK->>Config: saveGrantedPermissions
        SDK-->>User: status granted
    else mismatch or no initiator
        SDK-->>User: status failure - re-prompt
    end

    Note over User,Server: Sign-in path with early grant stash
    User->>SDK: signIn()
    SDK->>Config: clear stale stash and initiator
    SDK->>Server: PKCE redirect
    Server-->>SDK: pre-code callback with granted_permissions
    SDK->>Config: stashPendingGrantedPermissions(state, grants)
    SDK->>Server: obtainLocation - final callback
    Server-->>SDK: code and tokens
    SDK->>Config: union URL grants + stash + scope minus OIDC
    SDK->>Config: saveGrantedPermissions

Loading

_{Reviews (8): Last reviewed commit: "docs: consolidate highlights changesets ..." | Re-trigger Greptile}

Context used:

• File used - docs/review-guidelines.md (source)

[changeset-bot]

🦋 Changeset detected

Latest commit: 00b1ff4

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

This PR includes changesets to release 4 packages

Name	Type
@youversion/platform-core	Minor
@youversion/platform-react-hooks	Minor
@youversion/platform-react-ui	Minor
vite-react	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