feat: OAuth client scopes

[supalarry]

Fixes #26475

---

Summary by cubic

Adds OAuth client scopes across API, UI, and docs with strict scope-based endpoint access. Token and refresh responses now include a space-delimited scope; the authorize page validates state and requested scopes against the client’s registered scopes.

• New Features

  • Add OAuthClient.scopes[] and new AccessScope values; parse comma/space-delimited scope; include scope in token/refresh responses.
  • Enforce endpoint access via ThirdPartyPermissionsGuard using scope↔permission mapping; V2 docs/OpenAPI accept OAuth bearer tokens and list scopes.
  • UI/TRPC require scopes on create/submit, show scope selection, return client scopes for authorization, and validate requested scopes; legacy clients hide scopes and can update without scopes.
  • Broadening a client’s scopes sets status to PENDING for re-approval (write implies read when checking expansion).
  • Return invalid_scope (RFC 6749) when requested scopes are invalid or exceed the client’s registered scopes.

• Migration

  • Prisma migration adds new AccessScope values and the OAuthClient.scopes[] column.
  • New clients must select at least one scope; legacy clients continue to work and can opt in later.

^{Written for commit aaa4ac9. Summary will update on new commits.}

---

[paragon-review]

Paragon Review Unavailable

Hi @supalarry! To enable Paragon reviews on this repository, please register at https://home.polarity.cc

Once registered, connect your GitHub account and Paragon will automatically review your pull requests.

[linear]

CAL-7030 feat: OAuth client scopes

[cubic-dev-ai]

1 issue found across 28 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/trpc/server/routers/viewer/oAuth/updateClient.handler.ts">

<violation number="1" location="packages/trpc/server/routers/viewer/oAuth/updateClient.handler.ts:68">
P1: Security: Scope changes by owners should trigger reapproval. The `scopes` field is added to `hasAnyFieldsChanged()` but NOT to `triggersReapprovalForOwnerEdit()`. This allows OAuth client owners to escalate their client's permissions without admin oversight. Similar to how `redirectUri` changes require reapproval, scope modifications should also set status to PENDING.

The `triggersReapprovalForOwnerEdit()` call below (lines 79-93) needs to include `scopes` in both `currentClient` and `proposedUpdates` to maintain the approval workflow for permission changes.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[github-actions]

Devin AI is addressing Cubic AI's review feedback

A Devin session has been created to address the issues identified by Cubic AI.

View Devin Session

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 7 additional findings.

[cubic-dev-ai]

2 issues found across 2 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="apps/api/v2/src/modules/auth/guards/permissions/permissions.guard.spec.ts">

<violation number="1" location="apps/api/v2/src/modules/auth/guards/permissions/permissions.guard.spec.ts:152">
P3: Fix typo in test description: "compatability" → "compatibility" for clearer test naming.</violation>

<violation number="2" location="apps/api/v2/src/modules/auth/guards/permissions/permissions.guard.spec.ts:163">
P3: Fix typo in test description: "compatability" → "compatibility" for clearer test naming.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[github-actions]

Devin AI is addressing Cubic AI's review feedback

A Devin session has been created to address the issues identified by Cubic AI.

View Devin Session

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/web/modules/settings/oauth/view/OAuthClientDetailsDialog.tsx">

<violation number="1" location="apps/web/modules/settings/oauth/view/OAuthClientDetailsDialog.tsx:285">
P2: Legacy clients with empty scopes can no longer be updated because scope selection is hidden while the submit handler requires at least one scope. Allow scope selection when editing legacy clients (or bypass the required-scope check) so updates aren’t permanently blocked.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[github-actions]

Devin AI is addressing Cubic AI's review feedback

A Devin session has been created to address the issues identified by Cubic AI.

View Devin Session

---

✅ No changes pushed

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/web/playwright/oauth/oauth-authorize-approval-status.e2e.ts">

<violation number="1" location="apps/web/playwright/oauth/oauth-authorize-approval-status.e2e.ts:457">
P3: Unknown-scope errors map to the OAuth "invalid_scope" error, so this expectation will fail (or mask a regression). Update the assertion to expect invalid_scope.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[github-actions]

Devin AI is addressing Cubic AI's review feedback

A Devin session has been created to address the issues identified by Cubic AI.

View Devin Session