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';

<Protect permission="org:appointment:accept">
    <button>Accept appointment</button>
</Protect>

<Protect
  condition={has =>
    has({ permission: 'org:appointment:accept' }) || has({ permission: 'org:appointment:decline' })
  }>
     <button>Accept appointment</button>
     <button>Decline appointment</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'; 

<Protect permission="org:appointment:accept">
    <button>Accept appointment</button>
</Protect>

<Protect
  condition={has =>
    has({ permission: 'org:appointment:accept' }) || has({ permission: 'org:appointment:decline' })
  }>
     <button>Accept appointment</button>
     <button>Decline appointment</button>
</Protect>

`has` from the Auth object

import { auth } from '@clerk/nextjs';

const isAuthorized = auth().has({permission: "org:appointment:decline"})

import { getAuth } from '@clerk/remix';

const isAuthorized = 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 string

const {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.ts

interface ClerkAuthorization {
  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.ts

declare global {
  interface ClerkAuthorization {
    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):

<Protect condition={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 6c59374 Compare November 20, 2023 13:26

panteliselef requested a review from a team November 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 thread packages/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 9dfe2b3 Compare 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 bda5428 Compare 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 authorization Dec 4, 2023

panteliselef force-pushed the elef/core-810-gate-with-permissions branch from be85aef to 636a20a Compare 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 e07c709 Compare 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 79fff5a Compare 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 46040a2 Dec 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-bot Bot 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!

brkalow Dec 4, 2023

Choose a reason for hiding this comment

Uh oh!

panteliselef Dec 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-actions Bot 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-bot Bot commented Nov 20, 2023 •

edited

Loading

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