chore(backend,nextjs,types): Prevent system permissions usage in server-side #4816

LauraBeatris · 2024-12-19T17:48:32Z

Description

Resolves ORGS-441

Context

System permissions (e.g., org:sys_domains:manage) are intentionally excluded from session claims to maintain reasonable JWT sizes. While these permissions work in client-side authorization checks (where they're validated against FAPI organization memberships), they cannot be verified server-side.

Problem

Despite documentation updates, developers continue to use server-side authorization checks with system permissions, leading to confusion and support tickets.

Solution

Add type-level validation to catch misuse of system permissions during development. I've opted not to introduce a runtime warning since developers might ignore it.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

changeset-bot · 2024-12-19T17:48:36Z

🦋 Changeset detected

Latest commit: afad6c9

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/backend	Patch
@clerk/types	Patch
@clerk/nextjs	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/remix	Patch
@clerk/clerk-sdk-node	Patch
@clerk/tanstack-start	Patch
@clerk/testing	Patch
@clerk/clerk-js	Patch
@clerk/elements	Patch
@clerk/expo-passkeys	Patch
@clerk/clerk-expo	Patch
@clerk/localizations	Patch
@clerk/clerk-react	Patch
@clerk/shared	Patch
@clerk/themes	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/chrome-extension	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

vercel · 2024-12-19T17:48:36Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
clerk-js-sandbox	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 7, 2025 4:10pm

panteliselef · 2024-12-19T18:48:02Z

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

+  it('prevents usage of system permissions with auth.has()', () => {
+    clerkMiddlewareMock(async (auth, _event, _request) => {
+      // @ts-expect-error - system permissions are not allowed
+      (await auth()).has({ permission: 'org:sys_foo' });
+    });
+  });
+


do you think we should add a test case for useAuth() where the type says that sys permissions are allowed ?

In order to not break something in the future

Applied on 1da1b64

brkalow · 2024-12-20T03:21:04Z

packages/types/src/session.ts

+type DisallowSystemPermissions<P extends string> = P extends `${OrganizationSystemPermissionPrefix}${string}`
+  ? 'System permissions are not included in session claims and cannot be used on the server-side'
+  : P;


This is really cool!

panteliselef · 2025-01-07T12:53:20Z

This is great initiative. I opened another PR pointing to this one that also addresses usage with protect().

I noticed that type checking does not work currently in our unit tests, so I would avoid merging this PR until that is resolved.

panteliselef · 2025-01-07T13:40:33Z

🙃 Avoid merging until this is merged

jacekradko · 2025-01-07T19:31:52Z

I am curious what our stance is on these type-only (build-time) checks when it comes to users that don't use Typescript is their projects? Is there a downside to also have a run-time check/warning?

panteliselef · 2025-01-07T19:54:58Z

In this case it's mostly improved DX. You don't really care about DX if you are using JS in my opinion. But if you feel strongly a warning makes sense more than an error here. Since the utility will simply return false or redirect you.

LauraBeatris · 2025-01-07T21:18:11Z

Also worth mentioning that this requirement might change in the future, when we deal with the wider problem of session claims bloating the browser cookie size

Most developers might not even notice the console warning when running on the server-side, although I see the point that they won't get the DX benefits of type-checks when using JavaScript only

…er-side (#4816) Co-authored-by: panteliselef <panteliselef@outlook.com>

LauraBeatris self-assigned this Dec 19, 2024

clerk-cookie added types nextjs backend labels Dec 19, 2024

LauraBeatris force-pushed the laura/orgs-441-do-not-allow-passing-system-permissions-to-has-from-the branch from 4b60ed7 to 44bb684 Compare December 19, 2024 17:56

vercel bot deployed to Preview December 19, 2024 17:58 View deployment

LauraBeatris requested a review from panteliselef December 19, 2024 17:59

vercel bot deployed to Preview December 19, 2024 18:02 View deployment

LauraBeatris changed the title ~~chore(backend,types): Prevent system permissions usage in server-side~~ chore(backend,types): Prevent system permissions usage in server-side Dec 19, 2024

LauraBeatris force-pushed the laura/orgs-441-do-not-allow-passing-system-permissions-to-has-from-the branch from 65a25ba to ca63d27 Compare December 19, 2024 18:03

LauraBeatris requested a review from wobsoriano December 19, 2024 18:04

vercel bot deployed to Preview December 19, 2024 18:05 View deployment

LauraBeatris marked this pull request as ready for review December 19, 2024 18:10

panteliselef reviewed Dec 19, 2024

View reviewed changes

brkalow reviewed Dec 20, 2024

View reviewed changes

LauraBeatris added 4 commits January 6, 2025 16:06

Fix JSDocs for org_permissions

54797cd

Extract system permission prefix to a separate type

d07fb96

Add type guard from session claims

c3e6235

Add changeset

2f87d65

LauraBeatris force-pushed the laura/orgs-441-do-not-allow-passing-system-permissions-to-has-from-the branch from ca63d27 to 2f87d65 Compare January 6, 2025 19:06

vercel bot deployed to Preview January 6, 2025 19:08 View deployment

Add type test for useAuth.has

1da1b64

LauraBeatris requested review from brkalow and panteliselef January 6, 2025 19:22

clerk-cookie added the react label Jan 6, 2025

vercel bot deployed to Preview January 6, 2025 19:25 View deployment

chore(types,nextjs): Handle types in protect() (#4843)

2db90d3

LauraBeatris changed the title ~~chore(backend,types): Prevent system permissions usage in server-side~~ chore(backend,nextjs,types): Prevent system permissions usage in server-side Jan 7, 2025

vercel bot deployed to Preview January 7, 2025 13:32 View deployment

Include @clerk/nextjs on changeset

afad6c9

vercel bot deployed to Preview January 7, 2025 16:10 View deployment

panteliselef approved these changes Jan 8, 2025

View reviewed changes

wobsoriano approved these changes Jan 8, 2025

View reviewed changes

LauraBeatris merged commit 44cab60 into main Jan 8, 2025
29 checks passed

LauraBeatris deleted the laura/orgs-441-do-not-allow-passing-system-permissions-to-has-from-the branch January 8, 2025 18:58

clerk-cookie mentioned this pull request Jan 8, 2025

ci(repo): Version packages #4848

Merged

jakobevangelista pushed a commit that referenced this pull request Jan 9, 2025

chore(backend,nextjs,types): Prevent system permissions usage in serv…

002207a

…er-side (#4816) Co-authored-by: panteliselef <panteliselef@outlook.com>

wobsoriano pushed a commit that referenced this pull request Feb 8, 2025

chore(backend,nextjs,types): Prevent system permissions usage in serv…

31f6f25

…er-side (#4816) Co-authored-by: panteliselef <panteliselef@outlook.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

chore(backend,nextjs,types): Prevent system permissions usage in server-side #4816

chore(backend,nextjs,types): Prevent system permissions usage in server-side #4816

Uh oh!

LauraBeatris commented Dec 19, 2024 •

edited

Loading

Uh oh!

changeset-bot bot commented Dec 19, 2024 •

edited

Loading

Uh oh!

vercel bot commented Dec 19, 2024 •

edited

Loading

Uh oh!

panteliselef Dec 19, 2024

Uh oh!

LauraBeatris Jan 6, 2025

Uh oh!

brkalow Dec 20, 2024

Uh oh!

panteliselef commented Jan 7, 2025

Uh oh!

panteliselef commented Jan 7, 2025

Uh oh!

jacekradko commented Jan 7, 2025

Uh oh!

panteliselef commented Jan 7, 2025

Uh oh!

LauraBeatris commented Jan 7, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

chore(backend,nextjs,types): Prevent system permissions usage in server-side #4816

chore(backend,nextjs,types): Prevent system permissions usage in server-side #4816

Uh oh!

Conversation

LauraBeatris commented Dec 19, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Context

Problem

Solution

Checklist

Type of change

Uh oh!

changeset-bot bot commented Dec 19, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Dec 19, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

panteliselef Dec 19, 2024

Choose a reason for hiding this comment

Uh oh!

LauraBeatris Jan 6, 2025

Choose a reason for hiding this comment

Uh oh!

brkalow Dec 20, 2024

Choose a reason for hiding this comment

Uh oh!

panteliselef commented Jan 7, 2025

Uh oh!

panteliselef commented Jan 7, 2025

Uh oh!

jacekradko commented Jan 7, 2025

Uh oh!

panteliselef commented Jan 7, 2025

Uh oh!

LauraBeatris commented Jan 7, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

LauraBeatris commented Dec 19, 2024 •

edited

Loading

changeset-bot bot commented Dec 19, 2024 •

edited

Loading

vercel bot commented Dec 19, 2024 •

edited

Loading