refactor(auth): remove web_read/web_write scope dependency by joebon · Pull Request #11148 · polarsource/polar

joebon · 2026-04-22T07:20:50Z

Summary

Related Issue: #11126

Remove web_read/web_write from all authorization scope checks and enforce web-session-only access on WebUser* dependencies.

Depends on #11147

What

web_read/web_write removed from all 33 auth.py required_scopes sets
Web sessions created with all scopes (list(Scope)) instead of {web_read, web_write}
WebUserRead/WebUserWrite/WebUserOrAnonymous enforce web-session-only access via is_web_session() — API tokens are rejected
is_web_session() checks isinstance(session, UserSession)
Legacy session upgrade narrowed to exact {web_read, web_write} match — prevents upgrading read-only impersonation sessions
Impersonation sessions get read-only scopes (*:read)
web_write removed from OrgPolicyGuard defaults and AuthorizeMembersManage/AuthorizeOrgDelete
Finance guards (AuthorizeFinanceRead/AuthorizeFinanceWrite) use finance-specific scopes instead of defaults
Default test fixture scopes changed to set(Scope), test User subjects get mock UserSession

Why

web_read/web_write were never authorization scopes — they were a proxy for "is this a web session?" This conflated authentication method with authorization, and required every auth.py to include them as fallbacks for web sessions to pass scope checks.

How

WebUserRead/WebUserWrite now wrap the authenticator with an is_web_session() check that rejects API tokens
web_read/web_write kept in Scope enum for backward compat with in-flight sessions (safe to remove after 2026-05-22)
Legacy sessions with exactly {web_read, web_write} transparently upgraded in middleware

Checklist

This PR addresses a single concern (one bug fix, one feature, one refactor)
The diff is reasonably sized and easy to review
New functionality is covered by tests
Linting and type checking pass (uv run task lint && uv run task lint_types)
No unrelated changes or drive-by fixes are included

vercel · 2026-04-22T07:20:54Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
polar	Ready	Preview, Comment	Apr 23, 2026 3:06pm
polar-sandbox	Ready	Preview, Comment	Apr 23, 2026 3:06pm

github-actions · 2026-04-22T07:22:18Z

OpenAPI Changes

No changes detected in the OpenAPI schema.

github-actions · 2026-04-22T07:30:09Z

Preview Environment
URL: https://polar-preview-vm.taildbff7b.ts.net/pr-11148
API: https://polar-preview-vm.taildbff7b.ts.net/pr-11148/v1/
Logs: backend
SHA: 100b8c2eee3f74842b36ae250762d70fbedefe54

- AuthorizeFinanceRead/Write: use finance-specific scopes - AccountPolicyGuard/PayoutAccountPolicyGuard: explicit scope requirements - Blocked org filtering in get_by_account/get_by_payout_account - Write endpoints re-fetch entities on write session - Blocked org test

Web sessions now have all scopes. Test fixtures should match to avoid false 403s from scope checks on finance endpoints.

Web sessions get all scopes at login. Remove web_read/web_write from all auth.py required_scopes. Legacy sessions transparently upgraded in middleware. Search and impersonation references cleaned up.

- is_web_session: check isinstance(session, UserSession) - Legacy session upgrade: narrow to exact {web_read, web_write} match - Impersonation sessions: use read-only scopes

WebUserRead/WebUserWrite/WebUserOrAnonymous now check is_web_session() to reject API tokens (PATs, OATs). Previously these depended on web_read/web_write reserved scopes for this gate, but with those scopes removed, any token could access web-only endpoints (OAuth consent, email change, PAT management, etc.). Also removes web_read/web_write remnants from OrgPolicyGuard defaults and AuthorizeMembersManage/AuthorizeOrgDelete scope requirements. Test fixture updated to provide mock UserSession for User subjects so is_web_session() returns True in tests.

Keep the original _WebUserOrAnonymous name — the underscore prefix already distinguishes it from the public WebUserOrAnonymous. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Replace runtime filtering (`s for s in Scope if s.value.endswith(":read")`) with an explicit READ_ONLY_SCOPES set on the Scope module. Used for impersonation sessions that should only have read access. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Remove web_read/web_write from e2e test fixtures and OAT test scopes — these scopes no longer gate anything. Add explicit tests for the legacy session upgrade logic: - Legacy {web_read, web_write} sessions are upgraded to all scopes - Read-only impersonation sessions are NOT upgraded - Partial scope sets are NOT upgraded Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

AuthSubjectFixture defaults to set(Scope), so explicitly passing it is redundant. In multi-parametrize entries, an all-scopes variant alongside a specific-scope variant adds no coverage — removed the all-scopes entry. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

_EventTypeWrite had required_scopes=set() after web_write removal, meaning any token could write event types without scope checks. Should require events_write. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Yopi · 2026-04-23T15:21:20Z

        return json_schema


+READ_ONLY_SCOPES: set[Scope] = {


frankie567

A few nitpicks, but otherwise good to go :)

frankie567 · 2026-04-24T06:28:38Z

+) -> AuthSubject[Anonymous | User]:
+    """Allow anonymous or web-session users. Reject API tokens."""
+    if not is_anonymous(auth_subject) and not is_web_session(auth_subject):
+        raise Unauthorized()


I would say to raise NotPermitted (403), since the user is technically authenticated, but can't access. This was the previous behavior IIRC.

frankie567 · 2026-04-24T06:29:10Z

+) -> AuthSubject[User]:
+    """Allow web-session users only. Reject API tokens."""
+    if not is_web_session(auth_subject):
+        raise Unauthorized()


Same comment

frankie567 · 2026-04-24T06:30:02Z

+    Scope.organization_access_tokens_read,
+}
+
+RESERVED_SCOPES: set[Scope] = set()


We can probably get rid of this one then.

vercel Bot deployed to Preview – polar-sandbox April 22, 2026 07:22 View deployment

vercel Bot deployed to Preview – polar April 22, 2026 07:22 View deployment

joebon force-pushed the authz-reworked-step-3 branch from fdf26d2 to 7294f66 Compare April 22, 2026 09:24

joebon force-pushed the authz-reworked-step-4 branch 2 times, most recently from 8ee8a33 to 3f83453 Compare April 22, 2026 09:26

vercel Bot deployed to Preview – polar April 22, 2026 09:29 View deployment

vercel Bot deployed to Preview – polar-sandbox April 22, 2026 09:29 View deployment

joebon force-pushed the authz-reworked-step-4 branch from 3f83453 to 26db9b1 Compare April 22, 2026 09:34

joebon force-pushed the authz-reworked-step-3 branch from 7294f66 to 5ad420e Compare April 22, 2026 09:34

vercel Bot deployed to Preview – polar April 22, 2026 09:37 View deployment

vercel Bot deployed to Preview – polar-sandbox April 22, 2026 09:37 View deployment

joebon force-pushed the authz-reworked-step-4 branch from 26db9b1 to e921b44 Compare April 22, 2026 09:38

joebon force-pushed the authz-reworked-step-3 branch from 5ad420e to 038b3c6 Compare April 22, 2026 09:38

vercel Bot deployed to Preview – polar April 22, 2026 09:41 View deployment

vercel Bot deployed to Preview – polar-sandbox April 22, 2026 09:41 View deployment

joebon force-pushed the authz-reworked-step-3 branch from 038b3c6 to b5af1d7 Compare April 22, 2026 10:03

joebon force-pushed the authz-reworked-step-4 branch from e921b44 to 64ed93c Compare April 22, 2026 10:03

vercel Bot deployed to Preview – polar-sandbox April 22, 2026 10:06 View deployment

vercel Bot deployed to Preview – polar April 22, 2026 10:06 View deployment

joebon force-pushed the authz-reworked-step-3 branch from b5af1d7 to 88392b6 Compare April 22, 2026 10:27

joebon force-pushed the authz-reworked-step-4 branch from 64ed93c to 29229dd Compare April 22, 2026 10:27

vercel Bot deployed to Preview – polar April 22, 2026 10:30 View deployment

vercel Bot deployed to Preview – polar-sandbox April 22, 2026 10:30 View deployment

joebon force-pushed the authz-reworked-step-3 branch from 88392b6 to e1ded23 Compare April 22, 2026 10:39

joebon force-pushed the authz-reworked-step-4 branch from 29229dd to 197bb0b Compare April 22, 2026 10:39

vercel Bot deployed to Preview – polar April 22, 2026 10:42 View deployment

vercel Bot deployed to Preview – polar-sandbox April 22, 2026 10:42 View deployment

vercel Bot deployed to Preview – polar April 23, 2026 07:16 View deployment

vercel Bot deployed to Preview – polar-sandbox April 23, 2026 07:16 View deployment

joebon force-pushed the authz-reworked-step-4 branch from 2afdeae to 592b0c1 Compare April 23, 2026 08:00

joebon force-pushed the authz-reworked-step-3 branch from cce19fd to d715452 Compare April 23, 2026 08:00

vercel Bot deployed to Preview – polar April 23, 2026 08:03 View deployment

vercel Bot deployed to Preview – polar-sandbox April 23, 2026 08:03 View deployment

joebon force-pushed the authz-reworked-step-3 branch from d715452 to e408a73 Compare April 23, 2026 09:05

joebon force-pushed the authz-reworked-step-4 branch from 592b0c1 to 8247ac1 Compare April 23, 2026 09:05

vercel Bot deployed to Preview – polar-sandbox April 23, 2026 09:08 View deployment

vercel Bot deployed to Preview – polar April 23, 2026 09:09 View deployment

joebon force-pushed the authz-reworked-step-4 branch from 8247ac1 to 883a748 Compare April 23, 2026 09:10

vercel Bot deployed to Preview – polar April 23, 2026 09:13 View deployment

vercel Bot deployed to Preview – polar-sandbox April 23, 2026 09:13 View deployment

joebon force-pushed the authz-reworked-step-4 branch from 883a748 to a1b05b6 Compare April 23, 2026 09:14

vercel Bot deployed to Preview – polar-sandbox April 23, 2026 09:17 View deployment

vercel Bot deployed to Preview – polar April 23, 2026 09:17 View deployment

joebon force-pushed the authz-reworked-step-3 branch from e234b84 to b2b1d3c Compare April 23, 2026 09:21

joebon and others added 11 commits April 23, 2026 15:50

test: default AuthSubjectFixture scopes to set(Scope)

0dee537

Web sessions now have all scopes. Test fixtures should match to avoid false 403s from scope checks on finance endpoints.

refactor(auth): remove web_read/web_write scope dependency

2c63e86

Web sessions get all scopes at login. Remove web_read/web_write from all auth.py required_scopes. Legacy sessions transparently upgraded in middleware. Search and impersonation references cleaned up.

fix(auth): scope cleanup security hardening

71f52f6

- is_web_session: check isinstance(session, UserSession) - Legacy session upgrade: narrow to exact {web_read, web_write} match - Impersonation sessions: use read-only scopes

style: format scope cleanup

423d361

style: revert unnecessary _WebUserOrAnonymousAuth rename

c50467b

Keep the original _WebUserOrAnonymous name — the underscore prefix already distinguishes it from the public WebUserOrAnonymous. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Yopi approved these changes Apr 23, 2026

View reviewed changes

Comment thread server/polar/auth/scope.py

return json_schema

READ_ONLY_SCOPES: set[Scope] = {

Copy link
Copy Markdown

Contributor

Yopi Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good idea!

frankie567 reviewed Apr 24, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(auth): remove web_read/web_write scope dependency#11148

refactor(auth): remove web_read/web_write scope dependency#11148
joebon wants to merge 11 commits intomainfrom
authz-reworked-step-4

joebon commented Apr 22, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Apr 22, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 22, 2026

Uh oh!

github-actions Bot commented Apr 22, 2026 •

edited

Loading

Uh oh!

Yopi Apr 23, 2026

Uh oh!

frankie567 left a comment

Uh oh!

frankie567 Apr 24, 2026

Uh oh!

frankie567 Apr 24, 2026

Uh oh!

frankie567 Apr 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

joebon commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What

Why

How

Checklist

Uh oh!

vercel Bot commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 22, 2026

OpenAPI Changes

Uh oh!

github-actions Bot commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Yopi Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

frankie567 left a comment

Choose a reason for hiding this comment

Uh oh!

frankie567 Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

frankie567 Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

frankie567 Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

joebon commented Apr 22, 2026 •

edited

Loading

vercel Bot commented Apr 22, 2026 •

edited

Loading

github-actions Bot commented Apr 22, 2026 •

edited

Loading