feat(nextjs,shared,backend,clerk-react): Introduce Protect for authorization by panteliselef · Pull Request #2170 · clerk/javascript

panteliselef · 2023-11-20T13:19:37Z

Description

This PR builds upon the Experimental__Gate and experimental__has there introduced recently.

Rename Gate to Protect
Support for permission checks. (Previously only roles could be used)
Remove the experimental tags and prefixes
Drop some from the has utility and Protect. Protect now accepts a condition prop where a function is expected with the has being exposed as the param.
Protect can now be used without required props. In this case behaves as <SignedIn>, if no authorization props are passed.
has will throw an error if neither permission or role is passed.
Introduce auth().protect() for App Router.

auth().protect()

Allow per page protection in app router. This utility will automatically throw a 404 error if user is not authorized or authenticated.
When auth().protect() is called

inside a page or layout file it will render the nearest not-found component set by the developer
inside a route handler it will return empty response body with a 404 status code

Examples

RSC in Nextjs

import{Protect}from'@clerk/nextjs';<Protectpermission="org:appointment:accept"><button>Accept appointment</button></Protect><Protectcondition={has=>has({permission: 'org:appointment:accept'})||has({permission: 'org:appointment:decline'})}><button>Accept appointment</button><button>Declineappointment</button>
</Protect>

Client component

"use client"/** * As a client component * The client component is exposed also from `@clerk/clerk-react */import{Protect}from'@clerk/nextjs';<Protectpermission="org:appointment:accept"><button>Accept appointment</button></Protect><Protectcondition={has=>has({permission: 'org:appointment:accept'})||has({permission: 'org:appointment:decline'})}><button>Accept appointment</button><button>Declineappointment</button>
</Protect>

`has` from the Auth object

import{auth}from'@clerk/nextjs';constisAuthorized=auth().has({permission: "org:appointment:decline"})import{getAuth}from'@clerk/remix';constisAuthorized=getAuth().has({permission: "org:appointment:decline"})

`protect` from `auth()` only for App Router

import{auth}from'@clerk/nextjs';const{userId, ...restAuthObj}=auth().protect()// ^ userId is stringconst{userId, ...restAuthObj}=auth().protect({permission: "org:appointment:decline"})const{userId, ...restAuthObj}=auth().protect({role: "org:admin"})const{userId, ...restAuthObj}=auth().protect(has=>has({permission: "org:appointment:decline"}))

Type-safety for custom roles and permissions

Create a clerk.d.ts file and replace ClerkAuthorization with your own types

// clerk.d.tsinterfaceClerkAuthorization{role: 'org:admin'|'org:editor'|'org:viewer';permission: 'org:article:create'|'org:article:manage'|'org:article:publish';}

If the file is a module, you can do this

// clerk.d.tsdeclare global {interfaceClerkAuthorization{role: 'org:admin'|'org:editor'|'org:viewer';permission: 'org:article:create'|'org:article:manage'|'org:article:publish';}}export{};

Checklist

npm test runs as expected.
npm run 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

Packages affected

changeset-bot · 2023-11-20T13:19:40Z

🦋 Changeset detected

Latest commit: 79fff5a

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

This PR includes changesets to release 11 packages

Name	Type
@clerk/chrome-extension	Minor
@clerk/clerk-js	Minor
@clerk/backend	Minor
@clerk/nextjs	Minor
@clerk/clerk-react	Minor
@clerk/types	Minor
@clerk/clerk-expo	Patch
@clerk/fastify	Patch
gatsby-plugin-clerk	Patch
@clerk/remix	Patch
@clerk/clerk-sdk-node	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

panteliselef · 2023-11-27T11:51:33Z

!snapshot

panteliselef · 2023-12-03T15:13:07Z

!snapshot

clerk-cookie · 2023-12-03T15:14:59Z

Hey @panteliselef - the snapshot version command generated the following package versions:

Package	Version
@clerk/backend	1.0.1-snapshot.vbda5428
@clerk/chrome-extension	1.0.1-snapshot.vbda5428
@clerk/clerk-js	5.0.1-snapshot.vbda5428
@clerk/clerk-expo	1.0.1-snapshot.vbda5428
@clerk/fastify	1.0.1-snapshot.vbda5428
gatsby-plugin-clerk	5.0.1-snapshot.vbda5428
@clerk/localizations	2.0.1-snapshot.vbda5428
@clerk/nextjs	5.0.1-snapshot.vbda5428
@clerk/clerk-react	5.0.1-snapshot.vbda5428
@clerk/remix	4.0.1-snapshot.vbda5428
@clerk/clerk-sdk-node	5.0.1-snapshot.vbda5428
@clerk/shared	2.0.1-snapshot.vbda5428
@clerk/themes	2.0.1-snapshot.vbda5428
@clerk/types	4.0.1-snapshot.vbda5428

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/backend

npm i @clerk/backend@1.0.1-snapshot.vbda5428 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@1.0.1-snapshot.vbda5428 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@5.0.1-snapshot.vbda5428 --save-exact

@clerk/clerk-expo

npm i @clerk/clerk-expo@1.0.1-snapshot.vbda5428 --save-exact

@clerk/fastify

npm i @clerk/fastify@1.0.1-snapshot.vbda5428 --save-exact

gatsby-plugin-clerk

npm i gatsby-plugin-clerk@5.0.1-snapshot.vbda5428 --save-exact

@clerk/localizations

npm i @clerk/localizations@2.0.1-snapshot.vbda5428 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@5.0.1-snapshot.vbda5428 --save-exact

@clerk/clerk-react

npm i @clerk/clerk-react@5.0.1-snapshot.vbda5428 --save-exact

@clerk/remix

npm i @clerk/remix@4.0.1-snapshot.vbda5428 --save-exact

@clerk/clerk-sdk-node

npm i @clerk/clerk-sdk-node@5.0.1-snapshot.vbda5428 --save-exact

@clerk/shared

npm i @clerk/shared@2.0.1-snapshot.vbda5428 --save-exact

@clerk/themes

npm i @clerk/themes@2.0.1-snapshot.vbda5428 --save-exact

@clerk/types

npm i @clerk/types@4.0.1-snapshot.vbda5428 --save-exact

brkalow · 2023-12-04T16:29:24Z

 noAuthStatusMessage: authAuthHeaderMissing(),
 })(buildRequestLike());
+
+ (authObject as AuthSignedIn).protect = params => {


We talked about supporting redirectUrl as an optional parameter when doing authz checks, but I can't remember if we decided to omit that for the initial implementation 🤔
auth().protect({role: 'admin'},{redirectUrl: '/home'})

I think we are skipping this. Especially with something like notAuthorized we wouldn't need to support redirectUrl

LekoArts

Public API-wise I'd like to talk about this before we merge it (hence the request changes to block it):

<Protectcondition={has=>has({"org:appointment:accept"})||has({"org:appointment:decline"})}>

This feels inconsistent. It would need to be either of those two things:

Like the <Protect permission="foobar"> prop so without the {}
Like the rest of the has functions so { permission: "foobar" }

I'd prefer 2) as then has would be consistent everywhere

PR description was incorrect, implementation is like 2)

LekoArts

Good work 👍

… is signed out

…rue and no user or org

…hen user is signed out" This reverts commit cf736cc

github-actions · 2023-12-11T17:30:38Z

⚠️ Changes detected under the ClerkJS `ui` directory!

Don't forget to apply the same changes under the /ui.retheme directory:
packages/clerk-js/src/ui/** ➡️ packages/clerk-js/src/ui.retheme/**

Also, you may need to update the following files:

packages/localizations/src/en-US.retheme.ts
packages/localizations/src/index.retheme.ts
packages/types/src/appearance.retheme.ts
packages/types/src/clerk.retheme.ts
packages/types/src/index.retheme.ts
packages/types/src/localization.retheme.ts

panteliselef · 2023-12-11T17:40:04Z

!snapshot

clerk-cookie · 2023-12-11T17:42:43Z

Hey @panteliselef - the snapshot version command generated the following package versions:

Package	Version
@clerk/backend	1.0.1-snapshot.v79fff5a
@clerk/chrome-extension	1.0.1-snapshot.v79fff5a
@clerk/clerk-js	5.0.1-snapshot.v79fff5a
@clerk/clerk-expo	1.0.1-snapshot.v79fff5a
@clerk/fastify	1.0.1-snapshot.v79fff5a
gatsby-plugin-clerk	5.0.1-snapshot.v79fff5a
@clerk/localizations	2.0.1-snapshot.v79fff5a
@clerk/nextjs	5.0.1-snapshot.v79fff5a
@clerk/clerk-react	5.0.1-snapshot.v79fff5a
@clerk/remix	4.0.1-snapshot.v79fff5a
@clerk/clerk-sdk-node	5.0.1-snapshot.v79fff5a
@clerk/shared	2.0.1-snapshot.v79fff5a
@clerk/themes	2.0.1-snapshot.v79fff5a
@clerk/types	4.0.1-snapshot.v79fff5a

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/backend

npm i @clerk/backend@1.0.1-snapshot.v79fff5a --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@1.0.1-snapshot.v79fff5a --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@5.0.1-snapshot.v79fff5a --save-exact

@clerk/clerk-expo

npm i @clerk/clerk-expo@1.0.1-snapshot.v79fff5a --save-exact

@clerk/fastify

npm i @clerk/fastify@1.0.1-snapshot.v79fff5a --save-exact

gatsby-plugin-clerk

npm i gatsby-plugin-clerk@5.0.1-snapshot.v79fff5a --save-exact

@clerk/localizations

npm i @clerk/localizations@2.0.1-snapshot.v79fff5a --save-exact

@clerk/nextjs

npm i @clerk/nextjs@5.0.1-snapshot.v79fff5a --save-exact

@clerk/clerk-react

npm i @clerk/clerk-react@5.0.1-snapshot.v79fff5a --save-exact

@clerk/remix

npm i @clerk/remix@4.0.1-snapshot.v79fff5a --save-exact

@clerk/clerk-sdk-node

npm i @clerk/clerk-sdk-node@5.0.1-snapshot.v79fff5a --save-exact

@clerk/shared

npm i @clerk/shared@2.0.1-snapshot.v79fff5a --save-exact

@clerk/themes

npm i @clerk/themes@2.0.1-snapshot.v79fff5a --save-exact

@clerk/types

npm i @clerk/types@4.0.1-snapshot.v79fff5a --save-exact

…ization (#2170)

…ization (#2170) (#2309) * feat(nextjs,shared,backend,clerk-react): Introduce Protect for authorization (#2170) * fix(types): Avoid using `ts-expect-error` as it may fail for hosting apps * fix(types,nextjs): Improve complex type * fix(types): Typescript v5 cannot infer types correctly * fix(types): Update MembershipRole and OrganizationPermissionKey to not resolve to `any`

…ization (#2170) * feat(nextjs,shared,backend,clerk-react): Support permissions in Gate * chore(types,backend,clerk-react): Create type for OrganizationCustomPermissions * chore(types,backend,clerk-react): Create type for custom roles * chore(types,backend,clerk-react): Add changeset * chore(types,backend,clerk-react): Add comments * chore(types,nextjs): Remove custom types * fix(clerk-react): Missing `some` support for has in useAuth * chore(types,clerk-react): Use OrganizationCustomPermission for permissions in ssr * chore(nextjs): Drop redirect from RSC `<Gate/>` * feat(types,nextjs,clerk-react,backend): Rename Gate to Protect - Drop `some` from the `has` utility and Protect. Protect now accepts a `condition` prop where a function is expected with the `has` being exposed as the param. - Protect can now be used without required props. In this chae behaves as `<SignedIn>` if no authorization props are passed. - `has` will throw an error if neither `permission` or `role` is passed. * feat(nextjs): Introduce `auth().protect()` for App Router Allow per page protection in app router. This utility will automatically throw a 404 error if user is not authorized or authenticated. When `auth().protect()` is called - inside a page or layout file it will render the nearest `not-found` component set by the developer - inside a route handler it will return empty response body with a 404 status code * chore(types): Add `Key` prefix to OrganizationCustomPermission * chore(nextjs): Remove duplicate types * chore(nextjs): Minor improvements in readability * chore(nextjs): Mark protect utility as experimental for Nextjs * chore(nextjs): Minor improvements * fix(nextjs,clerk-react,backend): Utility `has` is undefined when user is signed out * fix(clerk-react): Utility `has` returns false when user isLoaded is true and no user or org * chore(clerk-react,nextjs): Improve comments * fix(clerk-react): Eliminate flickering of fallback for CSR applications * feat(types): Allow overriding of types for custom roles and permissions * chore(repo): Update changeset file * fix(types): `MembershipRole` will include custom roles if applicable * chore(nextjs): Improve readability of conditionals * Revert "fix(nextjs,clerk-react,backend): Utility `has` is undefined when user is signed out" This reverts commit cf736cc * fix(clerk-js,types): Remove `experimental` from checkAuthorization

panteliselef self-assigned this Nov 20, 2023

clerk-cookie added types clerk-js nextjs react backend labels Nov 20, 2023

panteliselef force-pushed the elef/core-810-gate-with-permissions branch from 049f69e to 6c59374Compare November 20, 2023 13:26

panteliselef requested a review from a teamNovember 20, 2023 13:26

brkalow reviewed Nov 20, 2023
View reviewed changes

Comment thread.changeset/chatty-beds-doubt.md Outdated

brkalow reviewed Nov 20, 2023
View reviewed changes

Comment thread.changeset/chatty-beds-doubt.md Outdated

brkalow reviewed Nov 20, 2023
View reviewed changes

Comment threadpackages/types/src/organizationMembership.ts Outdated

panteliselef requested review from a team and brkalow November 24, 2023 12:21

panteliselef force-pushed the elef/core-810-gate-with-permissions branch from 91c3ba3 to 9dfe2b3Compare November 27, 2023 11:51

This comment was marked as outdated.
Sign in to view

panteliselef force-pushed the elef/core-810-gate-with-permissions branch 2 times, most recently from 91bf440 to bda5428Compare December 3, 2023 15:01

clerk-cookie added the chrome-extension label Dec 3, 2023

panteliselef changed the title ~~feat(nextjs,shared,backend,clerk-react): Support permissions in Gate~~feat(nextjs,shared,backend,clerk-react): Introduce Protect for authorizationDec 4, 2023

panteliselef force-pushed the elef/core-810-gate-with-permissions branch from be85aef to 636a20aCompare December 4, 2023 10:00

panteliselef requested a review from nikosdouvlis December 4, 2023 16:32

brkalow reviewed Dec 4, 2023
View reviewed changes

LekoArts previously requested changes Dec 5, 2023
View reviewed changes

LekoArts reviewed Dec 6, 2023
View reviewed changes

panteliselef force-pushed the elef/core-810-gate-with-permissions branch from d4a99be to e07c709Compare December 6, 2023 11:36

panteliselef added 14 commits December 11, 2023 19:29

chore(nextjs): Remove duplicate types
4dc9b9f

chore(nextjs): Minor improvements in readability
7a218c7

chore(nextjs): Mark protect utility as experimental for Nextjs
3f154ad

chore(nextjs): Minor improvements
d4f7d49

fix(nextjs,clerk-react,backend): Utility has is undefined when user…
1d323ad
… is signed out

fix(clerk-react): Utility has returns false when user isLoaded is t…
a8d61dc
…rue and no user or org

chore(clerk-react,nextjs): Improve comments
48d64c5

fix(clerk-react): Eliminate flickering of fallback for CSR applications
e3a4c23

feat(types): Allow overriding of types for custom roles and permissions
819b6a0

chore(repo): Update changeset file
3c6e17e

fix(types): MembershipRole will include custom roles if applicable
64ad323

chore(nextjs): Improve readability of conditionals
87ea852

Revert "fix(nextjs,clerk-react,backend): Utility has is undefined w…
584c71c
…hen user is signed out" This reverts commit cf736cc

fix(clerk-js,types): Remove experimental from checkAuthorization
79fff5a

panteliselef force-pushed the elef/core-810-gate-with-permissions branch from 24efeec to 79fff5aCompare December 11, 2023 17:30

panteliselef added this pull request to the merge queue Dec 11, 2023

Merged via the queue into main with commit 46040a2Dec 11, 2023

panteliselef deleted the elef/core-810-gate-with-permissions branch December 11, 2023 17:52

clerk-cookie mentioned this pull request Dec 11, 2023
Version Packages (alpha-v5) #2308
Merged

panteliselef added a commit that referenced this pull request Dec 11, 2023
feat(nextjs,shared,backend,clerk-react): Introduce Protect for author…
508071b
…ization (#2170)

panteliselef added a commit that referenced this pull request Dec 11, 2023
feat(nextjs,shared,backend,clerk-react): Introduce Protect for author…
9199b6a
…ization (#2170)

panteliselef mentioned this pull request Dec 11, 2023
feat(nextjs,shared,backend,clerk-react): Introduce Protect for authorization (#2170) #2309
Merged
24 tasks

LekoArts mentioned this pull request Mar 13, 2024
fix(themes): Add tslib and @clerk/types as dependencies to @clerk/themes (#2665) #2987
Merged

LekoArts mentioned this pull request Aug 2, 2024
chore(repo): Correct changeset #3883
Merged

Uh oh!

Conversation

panteliselef commented Nov 20, 2023• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

auth().protect()

Examples

RSC in Nextjs

Client component

has from the Auth object

protect from auth() only for App Router

Type-safety for custom roles and permissions

Checklist

Type of change

Packages affected

Uh oh!

changeset-botBot commented Nov 20, 2023• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Uh oh!

Uh oh!

Uh oh!

panteliselef commented Nov 27, 2023

Uh oh!

This comment was marked as outdated.

panteliselef commented Dec 3, 2023

Uh oh!

clerk-cookie commented Dec 3, 2023

Uh oh!

Uh oh!

brkalowDec 4, 2023

Choose a reason for hiding this comment

Uh oh!

panteliselefDec 4, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

LekoArts left a comment

Choose a reason for hiding this comment

Uh oh!

LekoArts left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actionsBot commented Dec 11, 2023

⚠️ Changes detected under the ClerkJS ui directory!

Uh oh!

panteliselef commented Dec 11, 2023

Uh oh!

clerk-cookie commented Dec 11, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

panteliselef commented Nov 20, 2023•
edited
Loading

`has` from the Auth object

`protect` from `auth()` only for App Router

changeset-botBot commented Nov 20, 2023•
edited
Loading

⚠️ Changes detected under the ClerkJS `ui` directory!