feat(supabase): add bypassAuthSession option for service-role clients

[saakshigupta2002]

🔍 Description

This PR adds a new global.bypassAuthSession option to SupabaseClient to fix an issue where service-role clients would incorrectly use user session tokens instead of the service-role key when querying security_invoker views.

What changed?

• Added bypassAuthSession?: boolean option to SupabaseClientOptions.global
• Modified _getAccessToken() method in SupabaseClient to check bypassAuthSession before retrieving session tokens
• Added comprehensive test coverage with 4 new unit tests validating the new behavior
• Updated TypeScript type definitions with detailed JSDoc documentation

Why was this change needed?

When using a service-role key with security_invoker = true views or functions, PostgREST runs queries with the caller's permissions. The issue occurred because _getAccessToken() would prioritize the user's session token over the service-role key when both existed.

This caused permission errors when:

1. A client was initialized with a service-role key
2. A user session existed (from previous authentication)
3. Queries were made to security_invoker views that accessed restricted schemas (like auth.users)

The requests would run with the authenticated role (from the session token) instead of the service_role (from the API key), resulting in "permission denied" errors even though the client was configured with full admin privileges.

Closes #2045

Test Coverage

All 4 new tests pass successfully:

✅ Uses supabaseKey when bypassAuthSession: true even with active session
✅ Uses session token when bypassAuthSession: false (default behavior)
✅ Passes correct token to fetchWithAuth wrapper
✅ Stores bypassAuthSession value correctly

Alternative approaches considered:

• Always using service_role key for admin clients - Rejected because it would break existing functionality where admins might want to perform user-level operations
• Automatic detection based on key type - Rejected because it's not always possible to distinguish service_role keys from anon keys
• Per-query option - Rejected in favor of client-level configuration for consistency
• This approach provides explicit control while maintaining backward compatibility.

Summary by CodeRabbit

• New Features

  • Added bypassAuthSession configuration option. When enabled, the client uses the API key for Authorization on all requests, bypassing active user session tokens.

• Tests

  • Added test suite validating bypassAuthSession behavior, token selection, and header usage across authentication scenarios.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new bypassAuthSession client option and protected flag that, when enabled, makes the client use the API key for Authorization instead of any active user session; the flag is wired into token retrieval logic, types, and unit tests.

Changes

Cohort / File(s)	Summary
Type Definitions packages/core/supabase-js/src/lib/types.ts	Adds bypassAuthSession?: boolean to SupabaseClientOptions (global) with docs and examples describing server-side usage and security implications.
Core Client Implementation packages/core/supabase-js/src/SupabaseClient.ts	Introduces protected bypassAuthSession property initialized from settings; updates token retrieval paths so when bypassAuthSession is true the client uses the API key instead of session tokens for Authorization.
Test Suite packages/core/supabase-js/test/unit/SupabaseClient.test.ts	Adds "Bypass Auth Session" tests verifying behavior when flag is true/false, ensuring API key is used and session methods are not called when bypassing, and that headers/tokens are passed correctly.

Sequence Diagram(s)

sequenceDiagram
  participant Client as Client\n(SupabaseClient)
  participant Auth as Auth\n(session store)
  participant Fetch as Fetch\n(fetchWithAuth / Network)

  Client->>Client: check bypassAuthSession flag
  alt bypassAuthSession = true
    Client->>Client: use API key as token
  else bypassAuthSession = false
    Client->>Auth: getSession()
    Auth-->>Client: return session token
  end
  Client->>Fetch: fetchWithAuth(Authorization: token / apikey)
  Fetch->>Server: request with provided headers

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main feature: adding a bypassAuthSession option for service-role clients, which directly corresponds to the code changes.
Linked Issues check	✅ Passed	The PR implements the objective from issue #2045: enabling service-role clients to bypass cached user session tokens and use the API key for security_invoker views/functions.
Out of Scope Changes check	✅ Passed	All changes are within scope: bypassAuthSession option addition, token retrieval logic, type definitions, comprehensive tests, and documentation are all aligned with the PR objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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 and usage tips.}