fix(specs): correct third-party auth error propagation behavior

[grdsdev]

Summary

specs/client/authentication_integration/third_party_auth.md currently says a rejecting/throwing accessToken callback falls back to the anon key, the same as returning null:

If the callback returns null or rejects, the request proceeds unauthenticated (as the project's anon key) rather than failing the call outright...

That doesn't match supabase-js, which I'm treating as the reference implementation here. In fetchWithAuth (packages/core/supabase-js/src/lib/fetch.ts), the token getter is called unguarded:

const realToken = await getAccessToken()

No try/catch — a rejecting callback propagates and fails the request. Only a null return triggers the anon-key Authorization fallback. flutter's AuthHttpClient.send() follows the same pattern (unguarded await _getAccessToken()), and its _getAccessToken() explicitly rethrows session errors with the comment "Throw the error instead of making an API request with an expired token."

This PR:

• Splits the null case (anon-key fallback, unchanged) from the reject/throw case (must propagate and fail the call) in the spec's Behavior section.
• Adds a Notes section stating implementations must not catch-and-return-null on the callback, since that silently downgrades an authenticated request to an anonymous one instead of surfacing the failure.

This came up while reviewing supabase-swift#1233, where the Functions client's access-token closure used try?, converting any error (including one from a configured accessToken provider) into nil. Cross-checking JS/Flutter/Python confirmed JS and Flutter both propagate the error; this spec should reflect that as the source of truth so other SDKs (including Swift) can be checked against it going forward.

Test plan

• npm run validate passes in scripts/capability-matrix
• No feature ID or schema changes — spec-only correction

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e1179fed-9840-468a-b703-bd2a9bf37fd7

📥 Commits

Reviewing files that changed from the base of the PR and between d6bb1ab and fd77700.

📒 Files selected for processing (1)

• specs/client/authentication_integration/third_party_auth.md

💤 Files with no reviewable changes (1)

• specs/client/authentication_integration/third_party_auth.md

Included review availability: Your plan includes up to 1 review per rolling hour; 0 remain after this review.

---

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes

  • Third-party authentication requests now proceed unauthenticated only when explicitly allowed by the token callback.
  • Authentication callback errors now correctly fail the triggering request instead of silently falling back to anonymous access.

• Documentation

  • Clarified that authentication implementations must not suppress callback failures.

Walkthrough

The third-party authentication specification states that a null token sends an unauthenticated request. Rejected or throwing token callbacks propagate their errors and fail the request. Implementations must not catch callback errors and return null.

Merge Risk: ⚪ Minimal · up to fd777

This is a localized specification correction clarifying authentication error propagation, with no production code changes or merge-blocking risk remaining after normal checks and 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.}