feat(backend, clerk-js,clerk-react,shared,types): Add feature param to has

.changeset/curvy-teeth-watch.md

@@ -0,0 +1,9 @@
+---
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/shared': patch
+'@clerk/types': patch
+---
+
+Add feature param to has

packages/backend/src/tokens/authObjects.ts

@@ -43,6 +43,7 @@ type SignedInAuthObjectProperties = {
  * [fistFactorAge, secondFactorAge]
  */
  factorVerificationAge: [firstFactorAge: number, secondFactorAge: number] | null;
+ __experimental_features?: string | null;
 };
 
 /**
@@ -114,6 +115,7 @@ const generateSignedInAuthObjectProperties = (claims: JwtPayload): SignedInAuthO
  orgSlug: claims.org_slug,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features: claims.fea,
  };
 };
 
@@ -125,8 +127,18 @@ export function signedInAuthObject(
  sessionToken: string,
  sessionClaims: JwtPayload,
 ): SignedInAuthObject {
- const { actor, sessionId, sessionStatus, userId, orgId, orgRole, orgSlug, orgPermissions, factorVerificationAge } =
- generateSignedInAuthObjectProperties(sessionClaims);
+ const {
+ actor,
+ sessionId,
+ sessionStatus,
+ userId,
+ orgId,
+ orgRole,
+ orgSlug,
+ orgPermissions,
+ factorVerificationAge,
+ __experimental_features,
+ } = generateSignedInAuthObjectProperties(sessionClaims);
  const apiClient = createBackendApiClient(authenticateContext);
  const getToken = createGetToken({
  sessionId,
@@ -145,8 +157,16 @@ export function signedInAuthObject(
  orgSlug,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features,
  getToken,
- has: createCheckAuthorization({ orgId, orgRole, orgPermissions, userId, factorVerificationAge }),
+ has: createCheckAuthorization({
+ orgId,
+ orgRole,
+ orgPermissions,
+ userId,
+ factorVerificationAge,
+ __experimental_features,
+ }),
  debug: createDebug({ ...authenticateContext, sessionToken }),
  };
 }

packages/clerk-js/src/core/resources/Session.ts

@@ -115,6 +115,8 @@ export class Session extends BaseResource implements SessionResource {
  orgId: activeMembership?.id,
  orgRole: activeMembership?.role,
  orgPermissions: activeMembership?.permissions,
+ // TODO: retrieve features
+ __experimental_features: 'testfeature',
  })(params);
  };
 

packages/react/src/components/controlComponents.tsx

@@ -1,6 +1,7 @@
 import { deprecated } from '@clerk/shared/deprecated';
 import type {
  CheckAuthorizationWithCustomPermissions,
+ FeatureKey,
  HandleOAuthCallbackParams,
  OrganizationCustomPermissionKey,
  OrganizationCustomRoleKey,
@@ -61,21 +62,31 @@ export type ProtectProps = React.PropsWithChildren<
  condition?: never;
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  condition?: never;
  role?: never;
  permission: OrganizationCustomPermissionKey;
+ __experimental_feature?: never;
  }
  | {
  condition: (has: CheckAuthorizationWithCustomPermissions) => boolean;
  role?: never;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  condition?: never;
  role?: never;
  permission?: never;
+ __experimental_feature: FeatureKey;
+ }
+ | {
+ condition?: never;
+ role?: never;
+ permission?: never;
+ __experimental_feature?: never;
  }
  ) & {
  fallback?: React.ReactNode;
@@ -89,8 +100,10 @@ export type ProtectProps = React.PropsWithChildren<
  * ```
  * <Protect permission="a_permission_key" />
  * <Protect role="a_role_key" />
+ * <Protect __experimental_feature"a_feature_key" />
  * <Protect condition={(has) => has({permission:"a_permission_key"})} />
  * <Protect condition={(has) => has({role:"a_role_key"})} />
+ * <Protect condition={(has) => has({__experimental_feature:"a_feature_key"})} />
  * <Protect fallback={<p>Unauthorized</p>} />
  * ```
  */
@@ -127,7 +140,7 @@ export const Protect = ({ children, fallback, treatPendingAsSignedOut, ...restAu
  return unauthorized;
  }
 
- if (restAuthorizedParams.role || restAuthorizedParams.permission) {
+ if (restAuthorizedParams.role || restAuthorizedParams.permission || restAuthorizedParams.__experimental_feature) {
  if (has(restAuthorizedParams)) {
  return authorized;
  }

packages/react/src/hooks/useAuth.ts

@@ -144,7 +144,17 @@ export function useDerivedAuth(
  authObject: any,
  { treatPendingAsSignedOut = true }: PendingSessionOptions = {},
 ): UseAuthReturn {
- const { userId, orgId, orgRole, has, signOut, getToken, orgPermissions, factorVerificationAge } = authObject ?? {};
+ const {
+ userId,
+ orgId,
+ orgRole,
+ has,
+ signOut,
+ getToken,
+ orgPermissions,
+ factorVerificationAge,
+ __experimental_features,
+ } = authObject ?? {};
 
  const derivedHas = useCallback(
  (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
@@ -157,9 +167,10 @@ export function useDerivedAuth(
  orgRole,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features,
  })(params);
  },
- [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge],
+ [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge, __experimental_features],
  );
 
  const payload = resolveAuthState({

packages/shared/src/authorization.ts

@@ -20,13 +20,19 @@ type AuthorizationOptions = {
  orgRole: string | null | undefined;
  orgPermissions: string[] | null | undefined;
  factorVerificationAge: [number, number] | null;
+ __experimental_features?: string | null;
 };
 
 type CheckOrgAuthorization = (
  params: { role?: OrganizationCustomRoleKey; permission?: OrganizationCustomPermissionKey },
  { orgId, orgRole, orgPermissions }: AuthorizationOptions,
 ) => boolean | null;
 
+type CheckFeatureAuthorization = (
+ params: { __experimental_feature?: string },
+ { __experimental_features }: AuthorizationOptions,
+) => boolean | null;
+
 type CheckReverificationAuthorization = (
  params: {
  reverification?: ReverificationConfig;
@@ -85,6 +91,25 @@ const checkOrgAuthorization: CheckOrgAuthorization = (params, options) => {
  return null;
 };
 
+const checkFeatureAuthorization: CheckFeatureAuthorization = (param, options) => {
+ const { __experimental_feature: feature } = param;
+ const { __experimental_features } = options;
+
+ if (!feature) {
+ return null;
+ }
+
+ if (!__experimental_features) {
+ return null;
+ }
+
+ if (typeof __experimental_features === 'string') {
+ return __experimental_features.split(',').includes(feature);
+ }
+
+ return null;
+};
+
 const validateReverificationConfig = (config: ReverificationConfig | undefined | null) => {
  if (!config) {
  return false;
@@ -156,6 +181,11 @@ const createCheckAuthorization = (options: AuthorizationOptions): CheckAuthoriza
 
  const orgAuthorization = checkOrgAuthorization(params, options);
  const reverificationAuthorization = checkReverificationAuthorization(params, options);
+ const featureAuthorization = checkFeatureAuthorization(params, options);
+
+ if (featureAuthorization) {
+ return featureAuthorization;
+ }
 
  if ([orgAuthorization, reverificationAuthorization].some(a => a === null)) {
  return [orgAuthorization, reverificationAuthorization].some(a => a === true);
@@ -175,6 +205,7 @@ type AuthStateOptions = {
  orgRole?: OrganizationCustomRoleKey | null;
  orgSlug?: string | null;
  orgPermissions?: OrganizationCustomPermissionKey[] | null;
+ __experimental_features?: string | null;
  getToken: GetToken;
  signOut: SignOut;
  has: (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => boolean;

packages/types/src/authorization.ts

@@ -0,0 +1,34 @@
+declare global {
+ // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+ interface ClerkAuthorization {}
+}
+
+interface AuthorizationKeysBase {
+ role: string;
+ permission: string;
+ __experimental_feature: string;
+}
+
+interface AuthorizationKeysPlaceholder {
+ role: unknown;
+ permission: unknown;
+ __experimental_feature: unknown;
+}
+
+export type RoleKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['role'] extends string
+ ? ClerkAuthorization['role']
+ : AuthorizationKeysBase['role']
+ : AuthorizationKeysBase['role'];
+
+export type PermissionKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['permission'] extends string
+ ? ClerkAuthorization['permission']
+ : AuthorizationKeysBase['permission']
+ : AuthorizationKeysBase['permission'];
+
+export type FeatureKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['__experimental_feature'] extends string
+ ? ClerkAuthorization['__experimental_feature']
+ : AuthorizationKeysBase['__experimental_feature']
+ : AuthorizationKeysBase['__experimental_feature'];

packages/types/src/index.ts

@@ -3,6 +3,7 @@ export * from './appearance';
 export * from './elementIds';
 export * from './attributes';
 export * from './authConfig';
+export * from './authorization';
 export * from './backupCode';
 export * from './clerk';
 export * from './client';

packages/types/src/jwtv2.ts

@@ -119,14 +119,19 @@ type JWTPayloadBase = {
  * Any other JWT Claim Set member.
  */
  [propName: string]: unknown;
+
+ /**
+ * Feature claims, you can have multiple features in the same claim. e.g.: "impersonation,emails"
+ * @experimental
+ */
+ fea?: string | null;
 };
 
 export type VersionedJwtPayload =
  | {
  ver?: never;
 
  /**
- *
  * Active organization permissions.
  */
  org_permissions?: OrganizationCustomPermissionKey[];

packages/types/src/session.ts

@@ -1,3 +1,4 @@
+import type { FeatureKey } from './authorization';
 import type {
  BackupCodeAttempt,
  EmailCodeAttempt,
@@ -52,12 +53,19 @@ export type CheckAuthorizationParamsWithCustomPermissions = WithReverification<
  | {
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  role?: never;
  permission: OrganizationCustomPermissionKey;
+ __experimental_feature?: never;
  }
- | { role?: never; permission?: never }
+ | {
+ role?: never;
+ permission?: never;
+ __experimental_feature: FeatureKey;
+ }
+ | { role?: never; permission?: never; __experimental_feature?: never }
 >;
 
 export type CheckAuthorization = CheckAuthorizationFn<CheckAuthorizationParams>;
@@ -90,12 +98,19 @@ export type CheckAuthorizationParamsFromSessionClaims<P extends OrganizationCust
  | {
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  role?: never;
  permission: DisallowSystemPermissions<P>;
+ __experimental_feature?: never;
+ }
+ | {
+ role?: never;
+ permission?: never;
+ __experimental_feature: FeatureKey;
  }
- | { role?: never; permission?: never }
+ | { role?: never; permission?: never; __experimental_feature?: never }
 >;
 
 /**

.changeset/curvy-teeth-watch.md

@@ -0,0 +1,9 @@
+---
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/shared': patch
+'@clerk/types': patch
+---
+
+Add feature param to has

packages/backend/src/tokens/authObjects.ts

@@ -43,6 +43,7 @@ type SignedInAuthObjectProperties = {
  * [fistFactorAge, secondFactorAge]
  */
  factorVerificationAge: [firstFactorAge: number, secondFactorAge: number] | null;
+ __experimental_features?: string | null;
 };
 
 /**
@@ -114,6 +115,7 @@ const generateSignedInAuthObjectProperties = (claims: JwtPayload): SignedInAuthO
  orgSlug: claims.org_slug,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features: claims.fea,
  };
 };
 
@@ -125,8 +127,18 @@ export function signedInAuthObject(
  sessionToken: string,
  sessionClaims: JwtPayload,
 ): SignedInAuthObject {
- const { actor, sessionId, sessionStatus, userId, orgId, orgRole, orgSlug, orgPermissions, factorVerificationAge } =
- generateSignedInAuthObjectProperties(sessionClaims);
+ const {
+ actor,
+ sessionId,
+ sessionStatus,
+ userId,
+ orgId,
+ orgRole,
+ orgSlug,
+ orgPermissions,
+ factorVerificationAge,
+ __experimental_features,
+ } = generateSignedInAuthObjectProperties(sessionClaims);
  const apiClient = createBackendApiClient(authenticateContext);
  const getToken = createGetToken({
  sessionId,
@@ -145,8 +157,16 @@ export function signedInAuthObject(
  orgSlug,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features,
  getToken,
- has: createCheckAuthorization({ orgId, orgRole, orgPermissions, userId, factorVerificationAge }),
+ has: createCheckAuthorization({
+ orgId,
+ orgRole,
+ orgPermissions,
+ userId,
+ factorVerificationAge,
+ __experimental_features,
+ }),
  debug: createDebug({ ...authenticateContext, sessionToken }),
  };
 }

packages/clerk-js/src/core/resources/Session.ts

@@ -115,6 +115,8 @@ export class Session extends BaseResource implements SessionResource {
  orgId: activeMembership?.id,
  orgRole: activeMembership?.role,
  orgPermissions: activeMembership?.permissions,
+ // TODO: retrieve features
+ __experimental_features: 'testfeature',
  })(params);
  };
 

packages/react/src/components/controlComponents.tsx

@@ -1,6 +1,7 @@
 import { deprecated } from '@clerk/shared/deprecated';
 import type {
  CheckAuthorizationWithCustomPermissions,
+ FeatureKey,
  HandleOAuthCallbackParams,
  OrganizationCustomPermissionKey,
  OrganizationCustomRoleKey,
@@ -61,21 +62,31 @@ export type ProtectProps = React.PropsWithChildren<
  condition?: never;
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  condition?: never;
  role?: never;
  permission: OrganizationCustomPermissionKey;
+ __experimental_feature?: never;
  }
  | {
  condition: (has: CheckAuthorizationWithCustomPermissions) => boolean;
  role?: never;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  condition?: never;
  role?: never;
  permission?: never;
+ __experimental_feature: FeatureKey;
+ }
+ | {
+ condition?: never;
+ role?: never;
+ permission?: never;
+ __experimental_feature?: never;
  }
  ) & {
  fallback?: React.ReactNode;
@@ -89,8 +100,10 @@ export type ProtectProps = React.PropsWithChildren<
  * ```
  * <Protect permission="a_permission_key" />
  * <Protect role="a_role_key" />
+ * <Protect __experimental_feature"a_feature_key" />
  * <Protect condition={(has) => has({permission:"a_permission_key"})} />
  * <Protect condition={(has) => has({role:"a_role_key"})} />
+ * <Protect condition={(has) => has({__experimental_feature:"a_feature_key"})} />
  * <Protect fallback={<p>Unauthorized</p>} />
  * ```
  */
@@ -127,7 +140,7 @@ export const Protect = ({ children, fallback, treatPendingAsSignedOut, ...restAu
  return unauthorized;
  }
 
- if (restAuthorizedParams.role || restAuthorizedParams.permission) {
+ if (restAuthorizedParams.role || restAuthorizedParams.permission || restAuthorizedParams.__experimental_feature) {
  if (has(restAuthorizedParams)) {
  return authorized;
  }

packages/react/src/hooks/useAuth.ts

@@ -144,7 +144,17 @@ export function useDerivedAuth(
  authObject: any,
  { treatPendingAsSignedOut = true }: PendingSessionOptions = {},
 ): UseAuthReturn {
- const { userId, orgId, orgRole, has, signOut, getToken, orgPermissions, factorVerificationAge } = authObject ?? {};
+ const {
+ userId,
+ orgId,
+ orgRole,
+ has,
+ signOut,
+ getToken,
+ orgPermissions,
+ factorVerificationAge,
+ __experimental_features,
+ } = authObject ?? {};
 
  const derivedHas = useCallback(
  (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
@@ -157,9 +167,10 @@ export function useDerivedAuth(
  orgRole,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features,
  })(params);
  },
- [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge],
+ [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge, __experimental_features],
  );
 
  const payload = resolveAuthState({

packages/shared/src/authorization.ts

@@ -20,13 +20,19 @@ type AuthorizationOptions = {
  orgRole: string | null | undefined;
  orgPermissions: string[] | null | undefined;
  factorVerificationAge: [number, number] | null;
+ __experimental_features?: string | null;
 };
 
 type CheckOrgAuthorization = (
  params: { role?: OrganizationCustomRoleKey; permission?: OrganizationCustomPermissionKey },
  { orgId, orgRole, orgPermissions }: AuthorizationOptions,
 ) => boolean | null;
 
+type CheckFeatureAuthorization = (
+ params: { __experimental_feature?: string },
+ { __experimental_features }: AuthorizationOptions,
+) => boolean | null;
+
 type CheckReverificationAuthorization = (
  params: {
  reverification?: ReverificationConfig;
@@ -85,6 +91,25 @@ const checkOrgAuthorization: CheckOrgAuthorization = (params, options) => {
  return null;
 };
 
+const checkFeatureAuthorization: CheckFeatureAuthorization = (param, options) => {
+ const { __experimental_feature: feature } = param;
+ const { __experimental_features } = options;
+
+ if (!feature) {
+ return null;
+ }
+
+ if (!__experimental_features) {
+ return null;
+ }
+
+ if (typeof __experimental_features === 'string') {
+ return __experimental_features.split(',').includes(feature);
+ }
+
+ return null;
+};
+
 const validateReverificationConfig = (config: ReverificationConfig | undefined | null) => {
  if (!config) {
  return false;
@@ -156,6 +181,11 @@ const createCheckAuthorization = (options: AuthorizationOptions): CheckAuthoriza
 
  const orgAuthorization = checkOrgAuthorization(params, options);
  const reverificationAuthorization = checkReverificationAuthorization(params, options);
+ const featureAuthorization = checkFeatureAuthorization(params, options);
+
+ if (featureAuthorization) {
+ return featureAuthorization;
+ }
 
  if ([orgAuthorization, reverificationAuthorization].some(a => a === null)) {
  return [orgAuthorization, reverificationAuthorization].some(a => a === true);
@@ -175,6 +205,7 @@ type AuthStateOptions = {
  orgRole?: OrganizationCustomRoleKey | null;
  orgSlug?: string | null;
  orgPermissions?: OrganizationCustomPermissionKey[] | null;
+ __experimental_features?: string | null;
  getToken: GetToken;
  signOut: SignOut;
  has: (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => boolean;

packages/types/src/authorization.ts

@@ -0,0 +1,34 @@
+declare global {
+ // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+ interface ClerkAuthorization {}
+}
+
+interface AuthorizationKeysBase {
+ role: string;
+ permission: string;
+ __experimental_feature: string;
+}
+
+interface AuthorizationKeysPlaceholder {
+ role: unknown;
+ permission: unknown;
+ __experimental_feature: unknown;
+}
+
+export type RoleKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['role'] extends string
+ ? ClerkAuthorization['role']
+ : AuthorizationKeysBase['role']
+ : AuthorizationKeysBase['role'];
+
+export type PermissionKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['permission'] extends string
+ ? ClerkAuthorization['permission']
+ : AuthorizationKeysBase['permission']
+ : AuthorizationKeysBase['permission'];
+
+export type FeatureKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['__experimental_feature'] extends string
+ ? ClerkAuthorization['__experimental_feature']
+ : AuthorizationKeysBase['__experimental_feature']
+ : AuthorizationKeysBase['__experimental_feature'];

packages/types/src/index.ts

@@ -3,6 +3,7 @@ export * from './appearance';
 export * from './elementIds';
 export * from './attributes';
 export * from './authConfig';
+export * from './authorization';
 export * from './backupCode';
 export * from './clerk';
 export * from './client';

packages/types/src/jwtv2.ts

@@ -119,14 +119,19 @@ type JWTPayloadBase = {
  * Any other JWT Claim Set member.
  */
  [propName: string]: unknown;
+
+ /**
+ * Feature claims, you can have multiple features in the same claim. e.g.: "impersonation,emails"
+ * @experimental
+ */
+ fea?: string | null;
 };
 
 export type VersionedJwtPayload =
  | {
  ver?: never;
 
  /**
- *
  * Active organization permissions.
  */
  org_permissions?: OrganizationCustomPermissionKey[];

packages/types/src/session.ts

@@ -1,3 +1,4 @@
+import type { FeatureKey } from './authorization';
 import type {
  BackupCodeAttempt,
  EmailCodeAttempt,
@@ -52,12 +53,19 @@ export type CheckAuthorizationParamsWithCustomPermissions = WithReverification<
  | {
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  role?: never;
  permission: OrganizationCustomPermissionKey;
+ __experimental_feature?: never;
  }
- | { role?: never; permission?: never }
+ | {
+ role?: never;
+ permission?: never;
+ __experimental_feature: FeatureKey;
+ }
+ | { role?: never; permission?: never; __experimental_feature?: never }
 >;
 
 export type CheckAuthorization = CheckAuthorizationFn<CheckAuthorizationParams>;
@@ -90,12 +98,19 @@ export type CheckAuthorizationParamsFromSessionClaims<P extends OrganizationCust
  | {
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  role?: never;
  permission: DisallowSystemPermissions<P>;
+ __experimental_feature?: never;
+ }
+ | {
+ role?: never;
+ permission?: never;
+ __experimental_feature: FeatureKey;
  }
- | { role?: never; permission?: never }
+ | { role?: never; permission?: never; __experimental_feature?: never }
 >;
 
 /**

.changeset/curvy-teeth-watch.md

@@ -0,0 +1,9 @@
+---
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/shared': patch
+'@clerk/types': patch
+---
+
+Add feature param to has

packages/backend/src/tokens/authObjects.ts

@@ -43,6 +43,7 @@ type SignedInAuthObjectProperties = {
  * [fistFactorAge, secondFactorAge]
  */
  factorVerificationAge: [firstFactorAge: number, secondFactorAge: number] | null;
+ __experimental_features?: string | null;
 };
 
 /**
@@ -114,6 +115,7 @@ const generateSignedInAuthObjectProperties = (claims: JwtPayload): SignedInAuthO
  orgSlug: claims.org_slug,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features: claims.fea,
  };
 };
 
@@ -125,8 +127,18 @@ export function signedInAuthObject(
  sessionToken: string,
  sessionClaims: JwtPayload,
 ): SignedInAuthObject {
- const { actor, sessionId, sessionStatus, userId, orgId, orgRole, orgSlug, orgPermissions, factorVerificationAge } =
- generateSignedInAuthObjectProperties(sessionClaims);
+ const {
+ actor,
+ sessionId,
+ sessionStatus,
+ userId,
+ orgId,
+ orgRole,
+ orgSlug,
+ orgPermissions,
+ factorVerificationAge,
+ __experimental_features,
+ } = generateSignedInAuthObjectProperties(sessionClaims);
  const apiClient = createBackendApiClient(authenticateContext);
  const getToken = createGetToken({
  sessionId,
@@ -145,8 +157,16 @@ export function signedInAuthObject(
  orgSlug,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features,
  getToken,
- has: createCheckAuthorization({ orgId, orgRole, orgPermissions, userId, factorVerificationAge }),
+ has: createCheckAuthorization({
+ orgId,
+ orgRole,
+ orgPermissions,
+ userId,
+ factorVerificationAge,
+ __experimental_features,
+ }),
  debug: createDebug({ ...authenticateContext, sessionToken }),
  };
 }

packages/clerk-js/src/core/resources/Session.ts

@@ -115,6 +115,8 @@ export class Session extends BaseResource implements SessionResource {
  orgId: activeMembership?.id,
  orgRole: activeMembership?.role,
  orgPermissions: activeMembership?.permissions,
+ // TODO: retrieve features
+ __experimental_features: 'testfeature',
  })(params);
  };
 

packages/react/src/components/controlComponents.tsx

@@ -1,6 +1,7 @@
 import { deprecated } from '@clerk/shared/deprecated';
 import type {
  CheckAuthorizationWithCustomPermissions,
+ FeatureKey,
  HandleOAuthCallbackParams,
  OrganizationCustomPermissionKey,
  OrganizationCustomRoleKey,
@@ -61,21 +62,31 @@ export type ProtectProps = React.PropsWithChildren<
  condition?: never;
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  condition?: never;
  role?: never;
  permission: OrganizationCustomPermissionKey;
+ __experimental_feature?: never;
  }
  | {
  condition: (has: CheckAuthorizationWithCustomPermissions) => boolean;
  role?: never;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  condition?: never;
  role?: never;
  permission?: never;
+ __experimental_feature: FeatureKey;
+ }
+ | {
+ condition?: never;
+ role?: never;
+ permission?: never;
+ __experimental_feature?: never;
  }
  ) & {
  fallback?: React.ReactNode;
@@ -89,8 +100,10 @@ export type ProtectProps = React.PropsWithChildren<
  * ```
  * <Protect permission="a_permission_key" />
  * <Protect role="a_role_key" />
+ * <Protect __experimental_feature"a_feature_key" />
  * <Protect condition={(has) => has({permission:"a_permission_key"})} />
  * <Protect condition={(has) => has({role:"a_role_key"})} />
+ * <Protect condition={(has) => has({__experimental_feature:"a_feature_key"})} />
  * <Protect fallback={<p>Unauthorized</p>} />
  * ```
  */
@@ -127,7 +140,7 @@ export const Protect = ({ children, fallback, treatPendingAsSignedOut, ...restAu
  return unauthorized;
  }
 
- if (restAuthorizedParams.role || restAuthorizedParams.permission) {
+ if (restAuthorizedParams.role || restAuthorizedParams.permission || restAuthorizedParams.__experimental_feature) {
  if (has(restAuthorizedParams)) {
  return authorized;
  }

packages/react/src/hooks/useAuth.ts

@@ -144,7 +144,17 @@ export function useDerivedAuth(
  authObject: any,
  { treatPendingAsSignedOut = true }: PendingSessionOptions = {},
 ): UseAuthReturn {
- const { userId, orgId, orgRole, has, signOut, getToken, orgPermissions, factorVerificationAge } = authObject ?? {};
+ const {
+ userId,
+ orgId,
+ orgRole,
+ has,
+ signOut,
+ getToken,
+ orgPermissions,
+ factorVerificationAge,
+ __experimental_features,
+ } = authObject ?? {};
 
  const derivedHas = useCallback(
  (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
@@ -157,9 +167,10 @@ export function useDerivedAuth(
  orgRole,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features,
  })(params);
  },
- [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge],
+ [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge, __experimental_features],
  );
 
  const payload = resolveAuthState({

packages/shared/src/authorization.ts

@@ -20,13 +20,19 @@ type AuthorizationOptions = {
  orgRole: string | null | undefined;
  orgPermissions: string[] | null | undefined;
  factorVerificationAge: [number, number] | null;
+ __experimental_features?: string | null;
 };
 
 type CheckOrgAuthorization = (
  params: { role?: OrganizationCustomRoleKey; permission?: OrganizationCustomPermissionKey },
  { orgId, orgRole, orgPermissions }: AuthorizationOptions,
 ) => boolean | null;
 
+type CheckFeatureAuthorization = (
+ params: { __experimental_feature?: string },
+ { __experimental_features }: AuthorizationOptions,
+) => boolean | null;
+
 type CheckReverificationAuthorization = (
  params: {
  reverification?: ReverificationConfig;
@@ -85,6 +91,25 @@ const checkOrgAuthorization: CheckOrgAuthorization = (params, options) => {
  return null;
 };
 
+const checkFeatureAuthorization: CheckFeatureAuthorization = (param, options) => {
+ const { __experimental_feature: feature } = param;
+ const { __experimental_features } = options;
+
+ if (!feature) {
+ return null;
+ }
+
+ if (!__experimental_features) {
+ return null;
+ }
+
+ if (typeof __experimental_features === 'string') {
+ return __experimental_features.split(',').includes(feature);
+ }
+
+ return null;
+};
+
 const validateReverificationConfig = (config: ReverificationConfig | undefined | null) => {
  if (!config) {
  return false;
@@ -156,6 +181,11 @@ const createCheckAuthorization = (options: AuthorizationOptions): CheckAuthoriza
 
  const orgAuthorization = checkOrgAuthorization(params, options);
  const reverificationAuthorization = checkReverificationAuthorization(params, options);
+ const featureAuthorization = checkFeatureAuthorization(params, options);
+
+ if (featureAuthorization) {
+ return featureAuthorization;
+ }
 
  if ([orgAuthorization, reverificationAuthorization].some(a => a === null)) {
  return [orgAuthorization, reverificationAuthorization].some(a => a === true);
@@ -175,6 +205,7 @@ type AuthStateOptions = {
  orgRole?: OrganizationCustomRoleKey | null;
  orgSlug?: string | null;
  orgPermissions?: OrganizationCustomPermissionKey[] | null;
+ __experimental_features?: string | null;
  getToken: GetToken;
  signOut: SignOut;
  has: (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => boolean;

packages/types/src/authorization.ts

@@ -0,0 +1,34 @@
+declare global {
+ // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+ interface ClerkAuthorization {}
+}
+
+interface AuthorizationKeysBase {
+ role: string;
+ permission: string;
+ __experimental_feature: string;
+}
+
+interface AuthorizationKeysPlaceholder {
+ role: unknown;
+ permission: unknown;
+ __experimental_feature: unknown;
+}
+
+export type RoleKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['role'] extends string
+ ? ClerkAuthorization['role']
+ : AuthorizationKeysBase['role']
+ : AuthorizationKeysBase['role'];
+
+export type PermissionKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['permission'] extends string
+ ? ClerkAuthorization['permission']
+ : AuthorizationKeysBase['permission']
+ : AuthorizationKeysBase['permission'];
+
+export type FeatureKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['__experimental_feature'] extends string
+ ? ClerkAuthorization['__experimental_feature']
+ : AuthorizationKeysBase['__experimental_feature']
+ : AuthorizationKeysBase['__experimental_feature'];

packages/types/src/index.ts

@@ -3,6 +3,7 @@ export * from './appearance';
 export * from './elementIds';
 export * from './attributes';
 export * from './authConfig';
+export * from './authorization';
 export * from './backupCode';
 export * from './clerk';
 export * from './client';

packages/types/src/jwtv2.ts

@@ -119,14 +119,19 @@ type JWTPayloadBase = {
  * Any other JWT Claim Set member.
  */
  [propName: string]: unknown;
+
+ /**
+ * Feature claims, you can have multiple features in the same claim. e.g.: "impersonation,emails"
+ * @experimental
+ */
+ fea?: string | null;
 };
 
 export type VersionedJwtPayload =
  | {
  ver?: never;
 
  /**
- *
  * Active organization permissions.
  */
  org_permissions?: OrganizationCustomPermissionKey[];

packages/types/src/session.ts

@@ -1,3 +1,4 @@
+import type { FeatureKey } from './authorization';
 import type {
  BackupCodeAttempt,
  EmailCodeAttempt,
@@ -52,12 +53,19 @@ export type CheckAuthorizationParamsWithCustomPermissions = WithReverification<
  | {
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  role?: never;
  permission: OrganizationCustomPermissionKey;
+ __experimental_feature?: never;
  }
- | { role?: never; permission?: never }
+ | {
+ role?: never;
+ permission?: never;
+ __experimental_feature: FeatureKey;
+ }
+ | { role?: never; permission?: never; __experimental_feature?: never }
 >;
 
 export type CheckAuthorization = CheckAuthorizationFn<CheckAuthorizationParams>;
@@ -90,12 +98,19 @@ export type CheckAuthorizationParamsFromSessionClaims<P extends OrganizationCust
  | {
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  role?: never;
  permission: DisallowSystemPermissions<P>;
+ __experimental_feature?: never;
+ }
+ | {
+ role?: never;
+ permission?: never;
+ __experimental_feature: FeatureKey;
  }
- | { role?: never; permission?: never }
+ | { role?: never; permission?: never; __experimental_feature?: never }
 >;
 
 /**

.changeset/curvy-teeth-watch.md

@@ -0,0 +1,9 @@
+---
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/shared': patch
+'@clerk/types': patch
+---
+
+Add feature param to has

packages/backend/src/tokens/authObjects.ts

@@ -43,6 +43,7 @@ type SignedInAuthObjectProperties = {
  * [fistFactorAge, secondFactorAge]
  */
  factorVerificationAge: [firstFactorAge: number, secondFactorAge: number] | null;
+ __experimental_features?: string | null;
 };
 
 /**
@@ -114,6 +115,7 @@ const generateSignedInAuthObjectProperties = (claims: JwtPayload): SignedInAuthO
  orgSlug: claims.org_slug,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features: claims.fea,
  };
 };
 
@@ -125,8 +127,18 @@ export function signedInAuthObject(
  sessionToken: string,
  sessionClaims: JwtPayload,
 ): SignedInAuthObject {
- const { actor, sessionId, sessionStatus, userId, orgId, orgRole, orgSlug, orgPermissions, factorVerificationAge } =
- generateSignedInAuthObjectProperties(sessionClaims);
+ const {
+ actor,
+ sessionId,
+ sessionStatus,
+ userId,
+ orgId,
+ orgRole,
+ orgSlug,
+ orgPermissions,
+ factorVerificationAge,
+ __experimental_features,
+ } = generateSignedInAuthObjectProperties(sessionClaims);
  const apiClient = createBackendApiClient(authenticateContext);
  const getToken = createGetToken({
  sessionId,
@@ -145,8 +157,16 @@ export function signedInAuthObject(
  orgSlug,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features,
  getToken,
- has: createCheckAuthorization({ orgId, orgRole, orgPermissions, userId, factorVerificationAge }),
+ has: createCheckAuthorization({
+ orgId,
+ orgRole,
+ orgPermissions,
+ userId,
+ factorVerificationAge,
+ __experimental_features,
+ }),
  debug: createDebug({ ...authenticateContext, sessionToken }),
  };
 }

packages/clerk-js/src/core/resources/Session.ts

@@ -115,6 +115,8 @@ export class Session extends BaseResource implements SessionResource {
  orgId: activeMembership?.id,
  orgRole: activeMembership?.role,
  orgPermissions: activeMembership?.permissions,
+ // TODO: retrieve features
+ __experimental_features: 'testfeature',
  })(params);
  };
 

packages/react/src/components/controlComponents.tsx

@@ -1,6 +1,7 @@
 import { deprecated } from '@clerk/shared/deprecated';
 import type {
  CheckAuthorizationWithCustomPermissions,
+ FeatureKey,
  HandleOAuthCallbackParams,
  OrganizationCustomPermissionKey,
  OrganizationCustomRoleKey,
@@ -61,21 +62,31 @@ export type ProtectProps = React.PropsWithChildren<
  condition?: never;
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  condition?: never;
  role?: never;
  permission: OrganizationCustomPermissionKey;
+ __experimental_feature?: never;
  }
  | {
  condition: (has: CheckAuthorizationWithCustomPermissions) => boolean;
  role?: never;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  condition?: never;
  role?: never;
  permission?: never;
+ __experimental_feature: FeatureKey;
+ }
+ | {
+ condition?: never;
+ role?: never;
+ permission?: never;
+ __experimental_feature?: never;
  }
  ) & {
  fallback?: React.ReactNode;
@@ -89,8 +100,10 @@ export type ProtectProps = React.PropsWithChildren<
  * ```
  * <Protect permission="a_permission_key" />
  * <Protect role="a_role_key" />
+ * <Protect __experimental_feature"a_feature_key" />
  * <Protect condition={(has) => has({permission:"a_permission_key"})} />
  * <Protect condition={(has) => has({role:"a_role_key"})} />
+ * <Protect condition={(has) => has({__experimental_feature:"a_feature_key"})} />
  * <Protect fallback={<p>Unauthorized</p>} />
  * ```
  */
@@ -127,7 +140,7 @@ export const Protect = ({ children, fallback, treatPendingAsSignedOut, ...restAu
  return unauthorized;
  }
 
- if (restAuthorizedParams.role || restAuthorizedParams.permission) {
+ if (restAuthorizedParams.role || restAuthorizedParams.permission || restAuthorizedParams.__experimental_feature) {
  if (has(restAuthorizedParams)) {
  return authorized;
  }

packages/react/src/hooks/useAuth.ts

@@ -144,7 +144,17 @@ export function useDerivedAuth(
  authObject: any,
  { treatPendingAsSignedOut = true }: PendingSessionOptions = {},
 ): UseAuthReturn {
- const { userId, orgId, orgRole, has, signOut, getToken, orgPermissions, factorVerificationAge } = authObject ?? {};
+ const {
+ userId,
+ orgId,
+ orgRole,
+ has,
+ signOut,
+ getToken,
+ orgPermissions,
+ factorVerificationAge,
+ __experimental_features,
+ } = authObject ?? {};
 
  const derivedHas = useCallback(
  (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
@@ -157,9 +167,10 @@ export function useDerivedAuth(
  orgRole,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features,
  })(params);
  },
- [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge],
+ [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge, __experimental_features],
  );
 
  const payload = resolveAuthState({

packages/shared/src/authorization.ts

@@ -20,13 +20,19 @@ type AuthorizationOptions = {
  orgRole: string | null | undefined;
  orgPermissions: string[] | null | undefined;
  factorVerificationAge: [number, number] | null;
+ __experimental_features?: string | null;
 };
 
 type CheckOrgAuthorization = (
  params: { role?: OrganizationCustomRoleKey; permission?: OrganizationCustomPermissionKey },
  { orgId, orgRole, orgPermissions }: AuthorizationOptions,
 ) => boolean | null;
 
+type CheckFeatureAuthorization = (
+ params: { __experimental_feature?: string },
+ { __experimental_features }: AuthorizationOptions,
+) => boolean | null;
+
 type CheckReverificationAuthorization = (
  params: {
  reverification?: ReverificationConfig;
@@ -85,6 +91,25 @@ const checkOrgAuthorization: CheckOrgAuthorization = (params, options) => {
  return null;
 };
 
+const checkFeatureAuthorization: CheckFeatureAuthorization = (param, options) => {
+ const { __experimental_feature: feature } = param;
+ const { __experimental_features } = options;
+
+ if (!feature) {
+ return null;
+ }
+
+ if (!__experimental_features) {
+ return null;
+ }
+
+ if (typeof __experimental_features === 'string') {
+ return __experimental_features.split(',').includes(feature);
+ }
+
+ return null;
+};
+
 const validateReverificationConfig = (config: ReverificationConfig | undefined | null) => {
  if (!config) {
  return false;
@@ -156,6 +181,11 @@ const createCheckAuthorization = (options: AuthorizationOptions): CheckAuthoriza
 
  const orgAuthorization = checkOrgAuthorization(params, options);
  const reverificationAuthorization = checkReverificationAuthorization(params, options);
+ const featureAuthorization = checkFeatureAuthorization(params, options);
+
+ if (featureAuthorization) {
+ return featureAuthorization;
+ }
 
  if ([orgAuthorization, reverificationAuthorization].some(a => a === null)) {
  return [orgAuthorization, reverificationAuthorization].some(a => a === true);
@@ -175,6 +205,7 @@ type AuthStateOptions = {
  orgRole?: OrganizationCustomRoleKey | null;
  orgSlug?: string | null;
  orgPermissions?: OrganizationCustomPermissionKey[] | null;
+ __experimental_features?: string | null;
  getToken: GetToken;
  signOut: SignOut;
  has: (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => boolean;

packages/types/src/authorization.ts

@@ -0,0 +1,34 @@
+declare global {
+ // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+ interface ClerkAuthorization {}
+}
+
+interface AuthorizationKeysBase {
+ role: string;
+ permission: string;
+ __experimental_feature: string;
+}
+
+interface AuthorizationKeysPlaceholder {
+ role: unknown;
+ permission: unknown;
+ __experimental_feature: unknown;
+}
+
+export type RoleKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['role'] extends string
+ ? ClerkAuthorization['role']
+ : AuthorizationKeysBase['role']
+ : AuthorizationKeysBase['role'];
+
+export type PermissionKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['permission'] extends string
+ ? ClerkAuthorization['permission']
+ : AuthorizationKeysBase['permission']
+ : AuthorizationKeysBase['permission'];
+
+export type FeatureKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['__experimental_feature'] extends string
+ ? ClerkAuthorization['__experimental_feature']
+ : AuthorizationKeysBase['__experimental_feature']
+ : AuthorizationKeysBase['__experimental_feature'];

packages/types/src/index.ts

@@ -3,6 +3,7 @@ export * from './appearance';
 export * from './elementIds';
 export * from './attributes';
 export * from './authConfig';
+export * from './authorization';
 export * from './backupCode';
 export * from './clerk';
 export * from './client';

packages/types/src/jwtv2.ts

@@ -119,14 +119,19 @@ type JWTPayloadBase = {
  * Any other JWT Claim Set member.
  */
  [propName: string]: unknown;
+
+ /**
+ * Feature claims, you can have multiple features in the same claim. e.g.: "impersonation,emails"
+ * @experimental
+ */
+ fea?: string | null;
 };
 
 export type VersionedJwtPayload =
  | {
  ver?: never;
 
  /**
- *
  * Active organization permissions.
  */
  org_permissions?: OrganizationCustomPermissionKey[];

packages/types/src/session.ts

@@ -1,3 +1,4 @@
+import type { FeatureKey } from './authorization';
 import type {
  BackupCodeAttempt,
  EmailCodeAttempt,
@@ -52,12 +53,19 @@ export type CheckAuthorizationParamsWithCustomPermissions = WithReverification<
  | {
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  role?: never;
  permission: OrganizationCustomPermissionKey;
+ __experimental_feature?: never;
  }
- | { role?: never; permission?: never }
+ | {
+ role?: never;
+ permission?: never;
+ __experimental_feature: FeatureKey;
+ }
+ | { role?: never; permission?: never; __experimental_feature?: never }
 >;
 
 export type CheckAuthorization = CheckAuthorizationFn<CheckAuthorizationParams>;
@@ -90,12 +98,19 @@ export type CheckAuthorizationParamsFromSessionClaims<P extends OrganizationCust
  | {
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  role?: never;
  permission: DisallowSystemPermissions<P>;
+ __experimental_feature?: never;
+ }
+ | {
+ role?: never;
+ permission?: never;
+ __experimental_feature: FeatureKey;
  }
- | { role?: never; permission?: never }
+ | { role?: never; permission?: never; __experimental_feature?: never }
 >;
 
 /**

.changeset/curvy-teeth-watch.md

@@ -0,0 +1,9 @@
+---
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/shared': patch
+'@clerk/types': patch
+---
+
+Add feature param to has

packages/backend/src/tokens/authObjects.ts

@@ -43,6 +43,7 @@ type SignedInAuthObjectProperties = {
  * [fistFactorAge, secondFactorAge]
  */
  factorVerificationAge: [firstFactorAge: number, secondFactorAge: number] | null;
+ __experimental_features?: string | null;
 };
 
 /**
@@ -114,6 +115,7 @@ const generateSignedInAuthObjectProperties = (claims: JwtPayload): SignedInAuthO
  orgSlug: claims.org_slug,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features: claims.fea,
  };
 };
 
@@ -125,8 +127,18 @@ export function signedInAuthObject(
  sessionToken: string,
  sessionClaims: JwtPayload,
 ): SignedInAuthObject {
- const { actor, sessionId, sessionStatus, userId, orgId, orgRole, orgSlug, orgPermissions, factorVerificationAge } =
- generateSignedInAuthObjectProperties(sessionClaims);
+ const {
+ actor,
+ sessionId,
+ sessionStatus,
+ userId,
+ orgId,
+ orgRole,
+ orgSlug,
+ orgPermissions,
+ factorVerificationAge,
+ __experimental_features,
+ } = generateSignedInAuthObjectProperties(sessionClaims);
  const apiClient = createBackendApiClient(authenticateContext);
  const getToken = createGetToken({
  sessionId,
@@ -145,8 +157,16 @@ export function signedInAuthObject(
  orgSlug,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features,
  getToken,
- has: createCheckAuthorization({ orgId, orgRole, orgPermissions, userId, factorVerificationAge }),
+ has: createCheckAuthorization({
+ orgId,
+ orgRole,
+ orgPermissions,
+ userId,
+ factorVerificationAge,
+ __experimental_features,
+ }),
  debug: createDebug({ ...authenticateContext, sessionToken }),
  };
 }

packages/clerk-js/src/core/resources/Session.ts

@@ -115,6 +115,8 @@ export class Session extends BaseResource implements SessionResource {
  orgId: activeMembership?.id,
  orgRole: activeMembership?.role,
  orgPermissions: activeMembership?.permissions,
+ // TODO: retrieve features
+ __experimental_features: 'testfeature',
  })(params);
  };
 

packages/react/src/components/controlComponents.tsx

@@ -1,6 +1,7 @@
 import { deprecated } from '@clerk/shared/deprecated';
 import type {
  CheckAuthorizationWithCustomPermissions,
+ FeatureKey,
  HandleOAuthCallbackParams,
  OrganizationCustomPermissionKey,
  OrganizationCustomRoleKey,
@@ -61,21 +62,31 @@ export type ProtectProps = React.PropsWithChildren<
  condition?: never;
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  condition?: never;
  role?: never;
  permission: OrganizationCustomPermissionKey;
+ __experimental_feature?: never;
  }
  | {
  condition: (has: CheckAuthorizationWithCustomPermissions) => boolean;
  role?: never;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  condition?: never;
  role?: never;
  permission?: never;
+ __experimental_feature: FeatureKey;
+ }
+ | {
+ condition?: never;
+ role?: never;
+ permission?: never;
+ __experimental_feature?: never;
  }
  ) & {
  fallback?: React.ReactNode;
@@ -89,8 +100,10 @@ export type ProtectProps = React.PropsWithChildren<
  * ```
  * <Protect permission="a_permission_key" />
  * <Protect role="a_role_key" />
+ * <Protect __experimental_feature"a_feature_key" />
  * <Protect condition={(has) => has({permission:"a_permission_key"})} />
  * <Protect condition={(has) => has({role:"a_role_key"})} />
+ * <Protect condition={(has) => has({__experimental_feature:"a_feature_key"})} />
  * <Protect fallback={<p>Unauthorized</p>} />
  * ```
  */
@@ -127,7 +140,7 @@ export const Protect = ({ children, fallback, treatPendingAsSignedOut, ...restAu
  return unauthorized;
  }
 
- if (restAuthorizedParams.role || restAuthorizedParams.permission) {
+ if (restAuthorizedParams.role || restAuthorizedParams.permission || restAuthorizedParams.__experimental_feature) {
  if (has(restAuthorizedParams)) {
  return authorized;
  }

packages/react/src/hooks/useAuth.ts

@@ -144,7 +144,17 @@ export function useDerivedAuth(
  authObject: any,
  { treatPendingAsSignedOut = true }: PendingSessionOptions = {},
 ): UseAuthReturn {
- const { userId, orgId, orgRole, has, signOut, getToken, orgPermissions, factorVerificationAge } = authObject ?? {};
+ const {
+ userId,
+ orgId,
+ orgRole,
+ has,
+ signOut,
+ getToken,
+ orgPermissions,
+ factorVerificationAge,
+ __experimental_features,
+ } = authObject ?? {};
 
  const derivedHas = useCallback(
  (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
@@ -157,9 +167,10 @@ export function useDerivedAuth(
  orgRole,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features,
  })(params);
  },
- [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge],
+ [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge, __experimental_features],
  );
 
  const payload = resolveAuthState({

packages/shared/src/authorization.ts

@@ -20,13 +20,19 @@ type AuthorizationOptions = {
  orgRole: string | null | undefined;
  orgPermissions: string[] | null | undefined;
  factorVerificationAge: [number, number] | null;
+ __experimental_features?: string | null;
 };
 
 type CheckOrgAuthorization = (
  params: { role?: OrganizationCustomRoleKey; permission?: OrganizationCustomPermissionKey },
  { orgId, orgRole, orgPermissions }: AuthorizationOptions,
 ) => boolean | null;
 
+type CheckFeatureAuthorization = (
+ params: { __experimental_feature?: string },
+ { __experimental_features }: AuthorizationOptions,
+) => boolean | null;
+
 type CheckReverificationAuthorization = (
  params: {
  reverification?: ReverificationConfig;
@@ -85,6 +91,25 @@ const checkOrgAuthorization: CheckOrgAuthorization = (params, options) => {
  return null;
 };
 
+const checkFeatureAuthorization: CheckFeatureAuthorization = (param, options) => {
+ const { __experimental_feature: feature } = param;
+ const { __experimental_features } = options;
+
+ if (!feature) {
+ return null;
+ }
+
+ if (!__experimental_features) {
+ return null;
+ }
+
+ if (typeof __experimental_features === 'string') {
+ return __experimental_features.split(',').includes(feature);
+ }
+
+ return null;
+};
+
 const validateReverificationConfig = (config: ReverificationConfig | undefined | null) => {
  if (!config) {
  return false;
@@ -156,6 +181,11 @@ const createCheckAuthorization = (options: AuthorizationOptions): CheckAuthoriza
 
  const orgAuthorization = checkOrgAuthorization(params, options);
  const reverificationAuthorization = checkReverificationAuthorization(params, options);
+ const featureAuthorization = checkFeatureAuthorization(params, options);
+
+ if (featureAuthorization) {
+ return featureAuthorization;
+ }
 
  if ([orgAuthorization, reverificationAuthorization].some(a => a === null)) {
  return [orgAuthorization, reverificationAuthorization].some(a => a === true);
@@ -175,6 +205,7 @@ type AuthStateOptions = {
  orgRole?: OrganizationCustomRoleKey | null;
  orgSlug?: string | null;
  orgPermissions?: OrganizationCustomPermissionKey[] | null;
+ __experimental_features?: string | null;
  getToken: GetToken;
  signOut: SignOut;
  has: (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => boolean;

packages/types/src/authorization.ts

@@ -0,0 +1,34 @@
+declare global {
+ // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+ interface ClerkAuthorization {}
+}
+
+interface AuthorizationKeysBase {
+ role: string;
+ permission: string;
+ __experimental_feature: string;
+}
+
+interface AuthorizationKeysPlaceholder {
+ role: unknown;
+ permission: unknown;
+ __experimental_feature: unknown;
+}
+
+export type RoleKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['role'] extends string
+ ? ClerkAuthorization['role']
+ : AuthorizationKeysBase['role']
+ : AuthorizationKeysBase['role'];
+
+export type PermissionKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['permission'] extends string
+ ? ClerkAuthorization['permission']
+ : AuthorizationKeysBase['permission']
+ : AuthorizationKeysBase['permission'];
+
+export type FeatureKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['__experimental_feature'] extends string
+ ? ClerkAuthorization['__experimental_feature']
+ : AuthorizationKeysBase['__experimental_feature']
+ : AuthorizationKeysBase['__experimental_feature'];

packages/types/src/index.ts

@@ -3,6 +3,7 @@ export * from './appearance';
 export * from './elementIds';
 export * from './attributes';
 export * from './authConfig';
+export * from './authorization';
 export * from './backupCode';
 export * from './clerk';
 export * from './client';

packages/types/src/jwtv2.ts

@@ -119,14 +119,19 @@ type JWTPayloadBase = {
  * Any other JWT Claim Set member.
  */
  [propName: string]: unknown;
+
+ /**
+ * Feature claims, you can have multiple features in the same claim. e.g.: "impersonation,emails"
+ * @experimental
+ */
+ fea?: string | null;
 };
 
 export type VersionedJwtPayload =
  | {
  ver?: never;
 
  /**
- *
  * Active organization permissions.
  */
  org_permissions?: OrganizationCustomPermissionKey[];

packages/types/src/session.ts

@@ -1,3 +1,4 @@
+import type { FeatureKey } from './authorization';
 import type {
  BackupCodeAttempt,
  EmailCodeAttempt,
@@ -52,12 +53,19 @@ export type CheckAuthorizationParamsWithCustomPermissions = WithReverification<
  | {
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  role?: never;
  permission: OrganizationCustomPermissionKey;
+ __experimental_feature?: never;
  }
- | { role?: never; permission?: never }
+ | {
+ role?: never;
+ permission?: never;
+ __experimental_feature: FeatureKey;
+ }
+ | { role?: never; permission?: never; __experimental_feature?: never }
 >;
 
 export type CheckAuthorization = CheckAuthorizationFn<CheckAuthorizationParams>;
@@ -90,12 +98,19 @@ export type CheckAuthorizationParamsFromSessionClaims<P extends OrganizationCust
  | {
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  role?: never;
  permission: DisallowSystemPermissions<P>;
+ __experimental_feature?: never;
+ }
+ | {
+ role?: never;
+ permission?: never;
+ __experimental_feature: FeatureKey;
  }
- | { role?: never; permission?: never }
+ | { role?: never; permission?: never; __experimental_feature?: never }
 >;
 
 /**

.changeset/curvy-teeth-watch.md

@@ -0,0 +1,9 @@
+---
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/shared': patch
+'@clerk/types': patch
+---
+
+Add feature param to has

packages/backend/src/tokens/authObjects.ts

@@ -43,6 +43,7 @@ type SignedInAuthObjectProperties = {
  * [fistFactorAge, secondFactorAge]
  */
  factorVerificationAge: [firstFactorAge: number, secondFactorAge: number] | null;
+ __experimental_features?: string | null;
 };
 
 /**
@@ -114,6 +115,7 @@ const generateSignedInAuthObjectProperties = (claims: JwtPayload): SignedInAuthO
  orgSlug: claims.org_slug,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features: claims.fea,
  };
 };
 
@@ -125,8 +127,18 @@ export function signedInAuthObject(
  sessionToken: string,
  sessionClaims: JwtPayload,
 ): SignedInAuthObject {
- const { actor, sessionId, sessionStatus, userId, orgId, orgRole, orgSlug, orgPermissions, factorVerificationAge } =
- generateSignedInAuthObjectProperties(sessionClaims);
+ const {
+ actor,
+ sessionId,
+ sessionStatus,
+ userId,
+ orgId,
+ orgRole,
+ orgSlug,
+ orgPermissions,
+ factorVerificationAge,
+ __experimental_features,
+ } = generateSignedInAuthObjectProperties(sessionClaims);
  const apiClient = createBackendApiClient(authenticateContext);
  const getToken = createGetToken({
  sessionId,
@@ -145,8 +157,16 @@ export function signedInAuthObject(
  orgSlug,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features,
  getToken,
- has: createCheckAuthorization({ orgId, orgRole, orgPermissions, userId, factorVerificationAge }),
+ has: createCheckAuthorization({
+ orgId,
+ orgRole,
+ orgPermissions,
+ userId,
+ factorVerificationAge,
+ __experimental_features,
+ }),
  debug: createDebug({ ...authenticateContext, sessionToken }),
  };
 }

packages/clerk-js/src/core/resources/Session.ts

@@ -115,6 +115,8 @@ export class Session extends BaseResource implements SessionResource {
  orgId: activeMembership?.id,
  orgRole: activeMembership?.role,
  orgPermissions: activeMembership?.permissions,
+ // TODO: retrieve features
+ __experimental_features: 'testfeature',
  })(params);
  };
 

packages/react/src/components/controlComponents.tsx

@@ -1,6 +1,7 @@
 import { deprecated } from '@clerk/shared/deprecated';
 import type {
  CheckAuthorizationWithCustomPermissions,
+ FeatureKey,
  HandleOAuthCallbackParams,
  OrganizationCustomPermissionKey,
  OrganizationCustomRoleKey,
@@ -61,21 +62,31 @@ export type ProtectProps = React.PropsWithChildren<
  condition?: never;
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  condition?: never;
  role?: never;
  permission: OrganizationCustomPermissionKey;
+ __experimental_feature?: never;
  }
  | {
  condition: (has: CheckAuthorizationWithCustomPermissions) => boolean;
  role?: never;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  condition?: never;
  role?: never;
  permission?: never;
+ __experimental_feature: FeatureKey;
+ }
+ | {
+ condition?: never;
+ role?: never;
+ permission?: never;
+ __experimental_feature?: never;
  }
  ) & {
  fallback?: React.ReactNode;
@@ -89,8 +100,10 @@ export type ProtectProps = React.PropsWithChildren<
  * ```
  * <Protect permission="a_permission_key" />
  * <Protect role="a_role_key" />
+ * <Protect __experimental_feature"a_feature_key" />
  * <Protect condition={(has) => has({permission:"a_permission_key"})} />
  * <Protect condition={(has) => has({role:"a_role_key"})} />
+ * <Protect condition={(has) => has({__experimental_feature:"a_feature_key"})} />
  * <Protect fallback={<p>Unauthorized</p>} />
  * ```
  */
@@ -127,7 +140,7 @@ export const Protect = ({ children, fallback, treatPendingAsSignedOut, ...restAu
  return unauthorized;
  }
 
- if (restAuthorizedParams.role || restAuthorizedParams.permission) {
+ if (restAuthorizedParams.role || restAuthorizedParams.permission || restAuthorizedParams.__experimental_feature) {
  if (has(restAuthorizedParams)) {
  return authorized;
  }

packages/react/src/hooks/useAuth.ts

@@ -144,7 +144,17 @@ export function useDerivedAuth(
  authObject: any,
  { treatPendingAsSignedOut = true }: PendingSessionOptions = {},
 ): UseAuthReturn {
- const { userId, orgId, orgRole, has, signOut, getToken, orgPermissions, factorVerificationAge } = authObject ?? {};
+ const {
+ userId,
+ orgId,
+ orgRole,
+ has,
+ signOut,
+ getToken,
+ orgPermissions,
+ factorVerificationAge,
+ __experimental_features,
+ } = authObject ?? {};
 
  const derivedHas = useCallback(
  (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
@@ -157,9 +167,10 @@ export function useDerivedAuth(
  orgRole,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features,
  })(params);
  },
- [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge],
+ [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge, __experimental_features],
  );
 
  const payload = resolveAuthState({

packages/shared/src/authorization.ts

@@ -20,13 +20,19 @@ type AuthorizationOptions = {
  orgRole: string | null | undefined;
  orgPermissions: string[] | null | undefined;
  factorVerificationAge: [number, number] | null;
+ __experimental_features?: string | null;
 };
 
 type CheckOrgAuthorization = (
  params: { role?: OrganizationCustomRoleKey; permission?: OrganizationCustomPermissionKey },
  { orgId, orgRole, orgPermissions }: AuthorizationOptions,
 ) => boolean | null;
 
+type CheckFeatureAuthorization = (
+ params: { __experimental_feature?: string },
+ { __experimental_features }: AuthorizationOptions,
+) => boolean | null;
+
 type CheckReverificationAuthorization = (
  params: {
  reverification?: ReverificationConfig;
@@ -85,6 +91,25 @@ const checkOrgAuthorization: CheckOrgAuthorization = (params, options) => {
  return null;
 };
 
+const checkFeatureAuthorization: CheckFeatureAuthorization = (param, options) => {
+ const { __experimental_feature: feature } = param;
+ const { __experimental_features } = options;
+
+ if (!feature) {
+ return null;
+ }
+
+ if (!__experimental_features) {
+ return null;
+ }
+
+ if (typeof __experimental_features === 'string') {
+ return __experimental_features.split(',').includes(feature);
+ }
+
+ return null;
+};
+
 const validateReverificationConfig = (config: ReverificationConfig | undefined | null) => {
  if (!config) {
  return false;
@@ -156,6 +181,11 @@ const createCheckAuthorization = (options: AuthorizationOptions): CheckAuthoriza
 
  const orgAuthorization = checkOrgAuthorization(params, options);
  const reverificationAuthorization = checkReverificationAuthorization(params, options);
+ const featureAuthorization = checkFeatureAuthorization(params, options);
+
+ if (featureAuthorization) {
+ return featureAuthorization;
+ }
 
  if ([orgAuthorization, reverificationAuthorization].some(a => a === null)) {
  return [orgAuthorization, reverificationAuthorization].some(a => a === true);
@@ -175,6 +205,7 @@ type AuthStateOptions = {
  orgRole?: OrganizationCustomRoleKey | null;
  orgSlug?: string | null;
  orgPermissions?: OrganizationCustomPermissionKey[] | null;
+ __experimental_features?: string | null;
  getToken: GetToken;
  signOut: SignOut;
  has: (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => boolean;

packages/types/src/authorization.ts

@@ -0,0 +1,34 @@
+declare global {
+ // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+ interface ClerkAuthorization {}
+}
+
+interface AuthorizationKeysBase {
+ role: string;
+ permission: string;
+ __experimental_feature: string;
+}
+
+interface AuthorizationKeysPlaceholder {
+ role: unknown;
+ permission: unknown;
+ __experimental_feature: unknown;
+}
+
+export type RoleKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['role'] extends string
+ ? ClerkAuthorization['role']
+ : AuthorizationKeysBase['role']
+ : AuthorizationKeysBase['role'];
+
+export type PermissionKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['permission'] extends string
+ ? ClerkAuthorization['permission']
+ : AuthorizationKeysBase['permission']
+ : AuthorizationKeysBase['permission'];
+
+export type FeatureKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['__experimental_feature'] extends string
+ ? ClerkAuthorization['__experimental_feature']
+ : AuthorizationKeysBase['__experimental_feature']
+ : AuthorizationKeysBase['__experimental_feature'];

packages/types/src/index.ts

@@ -3,6 +3,7 @@ export * from './appearance';
 export * from './elementIds';
 export * from './attributes';
 export * from './authConfig';
+export * from './authorization';
 export * from './backupCode';
 export * from './clerk';
 export * from './client';

packages/types/src/jwtv2.ts

@@ -119,14 +119,19 @@ type JWTPayloadBase = {
  * Any other JWT Claim Set member.
  */
  [propName: string]: unknown;
+
+ /**
+ * Feature claims, you can have multiple features in the same claim. e.g.: "impersonation,emails"
+ * @experimental
+ */
+ fea?: string | null;
 };
 
 export type VersionedJwtPayload =
  | {
  ver?: never;
 
  /**
- *
  * Active organization permissions.
  */
  org_permissions?: OrganizationCustomPermissionKey[];

packages/types/src/session.ts

@@ -1,3 +1,4 @@
+import type { FeatureKey } from './authorization';
 import type {
  BackupCodeAttempt,
  EmailCodeAttempt,
@@ -52,12 +53,19 @@ export type CheckAuthorizationParamsWithCustomPermissions = WithReverification<
  | {
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  role?: never;
  permission: OrganizationCustomPermissionKey;
+ __experimental_feature?: never;
  }
- | { role?: never; permission?: never }
+ | {
+ role?: never;
+ permission?: never;
+ __experimental_feature: FeatureKey;
+ }
+ | { role?: never; permission?: never; __experimental_feature?: never }
 >;
 
 export type CheckAuthorization = CheckAuthorizationFn<CheckAuthorizationParams>;
@@ -90,12 +98,19 @@ export type CheckAuthorizationParamsFromSessionClaims<P extends OrganizationCust
  | {
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  role?: never;
  permission: DisallowSystemPermissions<P>;
+ __experimental_feature?: never;
+ }
+ | {
+ role?: never;
+ permission?: never;
+ __experimental_feature: FeatureKey;
  }
- | { role?: never; permission?: never }
+ | { role?: never; permission?: never; __experimental_feature?: never }
 >;
 
 /**

.changeset/curvy-teeth-watch.md

@@ -0,0 +1,9 @@
+---
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/shared': patch
+'@clerk/types': patch
+---
+
+Add feature param to has

packages/backend/src/tokens/authObjects.ts

@@ -43,6 +43,7 @@ type SignedInAuthObjectProperties = {
  * [fistFactorAge, secondFactorAge]
  */
  factorVerificationAge: [firstFactorAge: number, secondFactorAge: number] | null;
+ __experimental_features?: string | null;
 };
 
 /**
@@ -114,6 +115,7 @@ const generateSignedInAuthObjectProperties = (claims: JwtPayload): SignedInAuthO
  orgSlug: claims.org_slug,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features: claims.fea,
  };
 };
 
@@ -125,8 +127,18 @@ export function signedInAuthObject(
  sessionToken: string,
  sessionClaims: JwtPayload,
 ): SignedInAuthObject {
- const { actor, sessionId, sessionStatus, userId, orgId, orgRole, orgSlug, orgPermissions, factorVerificationAge } =
- generateSignedInAuthObjectProperties(sessionClaims);
+ const {
+ actor,
+ sessionId,
+ sessionStatus,
+ userId,
+ orgId,
+ orgRole,
+ orgSlug,
+ orgPermissions,
+ factorVerificationAge,
+ __experimental_features,
+ } = generateSignedInAuthObjectProperties(sessionClaims);
  const apiClient = createBackendApiClient(authenticateContext);
  const getToken = createGetToken({
  sessionId,
@@ -145,8 +157,16 @@ export function signedInAuthObject(
  orgSlug,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features,
  getToken,
- has: createCheckAuthorization({ orgId, orgRole, orgPermissions, userId, factorVerificationAge }),
+ has: createCheckAuthorization({
+ orgId,
+ orgRole,
+ orgPermissions,
+ userId,
+ factorVerificationAge,
+ __experimental_features,
+ }),
  debug: createDebug({ ...authenticateContext, sessionToken }),
  };
 }

packages/clerk-js/src/core/resources/Session.ts

@@ -115,6 +115,8 @@ export class Session extends BaseResource implements SessionResource {
  orgId: activeMembership?.id,
  orgRole: activeMembership?.role,
  orgPermissions: activeMembership?.permissions,
+ // TODO: retrieve features
+ __experimental_features: 'testfeature',
  })(params);
  };
 

packages/react/src/components/controlComponents.tsx

@@ -1,6 +1,7 @@
 import { deprecated } from '@clerk/shared/deprecated';
 import type {
  CheckAuthorizationWithCustomPermissions,
+ FeatureKey,
  HandleOAuthCallbackParams,
  OrganizationCustomPermissionKey,
  OrganizationCustomRoleKey,
@@ -61,21 +62,31 @@ export type ProtectProps = React.PropsWithChildren<
  condition?: never;
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  condition?: never;
  role?: never;
  permission: OrganizationCustomPermissionKey;
+ __experimental_feature?: never;
  }
  | {
  condition: (has: CheckAuthorizationWithCustomPermissions) => boolean;
  role?: never;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  condition?: never;
  role?: never;
  permission?: never;
+ __experimental_feature: FeatureKey;
+ }
+ | {
+ condition?: never;
+ role?: never;
+ permission?: never;
+ __experimental_feature?: never;
  }
  ) & {
  fallback?: React.ReactNode;
@@ -89,8 +100,10 @@ export type ProtectProps = React.PropsWithChildren<
  * ```
  * <Protect permission="a_permission_key" />
  * <Protect role="a_role_key" />
+ * <Protect __experimental_feature"a_feature_key" />
  * <Protect condition={(has) => has({permission:"a_permission_key"})} />
  * <Protect condition={(has) => has({role:"a_role_key"})} />
+ * <Protect condition={(has) => has({__experimental_feature:"a_feature_key"})} />
  * <Protect fallback={<p>Unauthorized</p>} />
  * ```
  */
@@ -127,7 +140,7 @@ export const Protect = ({ children, fallback, treatPendingAsSignedOut, ...restAu
  return unauthorized;
  }
 
- if (restAuthorizedParams.role || restAuthorizedParams.permission) {
+ if (restAuthorizedParams.role || restAuthorizedParams.permission || restAuthorizedParams.__experimental_feature) {
  if (has(restAuthorizedParams)) {
  return authorized;
  }

packages/react/src/hooks/useAuth.ts

@@ -144,7 +144,17 @@ export function useDerivedAuth(
  authObject: any,
  { treatPendingAsSignedOut = true }: PendingSessionOptions = {},
 ): UseAuthReturn {
- const { userId, orgId, orgRole, has, signOut, getToken, orgPermissions, factorVerificationAge } = authObject ?? {};
+ const {
+ userId,
+ orgId,
+ orgRole,
+ has,
+ signOut,
+ getToken,
+ orgPermissions,
+ factorVerificationAge,
+ __experimental_features,
+ } = authObject ?? {};
 
  const derivedHas = useCallback(
  (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
@@ -157,9 +167,10 @@ export function useDerivedAuth(
  orgRole,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features,
  })(params);
  },
- [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge],
+ [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge, __experimental_features],
  );
 
  const payload = resolveAuthState({

packages/shared/src/authorization.ts

@@ -20,13 +20,19 @@ type AuthorizationOptions = {
  orgRole: string | null | undefined;
  orgPermissions: string[] | null | undefined;
  factorVerificationAge: [number, number] | null;
+ __experimental_features?: string | null;
 };
 
 type CheckOrgAuthorization = (
  params: { role?: OrganizationCustomRoleKey; permission?: OrganizationCustomPermissionKey },
  { orgId, orgRole, orgPermissions }: AuthorizationOptions,
 ) => boolean | null;
 
+type CheckFeatureAuthorization = (
+ params: { __experimental_feature?: string },
+ { __experimental_features }: AuthorizationOptions,
+) => boolean | null;
+
 type CheckReverificationAuthorization = (
  params: {
  reverification?: ReverificationConfig;
@@ -85,6 +91,25 @@ const checkOrgAuthorization: CheckOrgAuthorization = (params, options) => {
  return null;
 };
 
+const checkFeatureAuthorization: CheckFeatureAuthorization = (param, options) => {
+ const { __experimental_feature: feature } = param;
+ const { __experimental_features } = options;
+
+ if (!feature) {
+ return null;
+ }
+
+ if (!__experimental_features) {
+ return null;
+ }
+
+ if (typeof __experimental_features === 'string') {
+ return __experimental_features.split(',').includes(feature);
+ }
+
+ return null;
+};
+
 const validateReverificationConfig = (config: ReverificationConfig | undefined | null) => {
  if (!config) {
  return false;
@@ -156,6 +181,11 @@ const createCheckAuthorization = (options: AuthorizationOptions): CheckAuthoriza
 
  const orgAuthorization = checkOrgAuthorization(params, options);
  const reverificationAuthorization = checkReverificationAuthorization(params, options);
+ const featureAuthorization = checkFeatureAuthorization(params, options);
+
+ if (featureAuthorization) {
+ return featureAuthorization;
+ }
 
  if ([orgAuthorization, reverificationAuthorization].some(a => a === null)) {
  return [orgAuthorization, reverificationAuthorization].some(a => a === true);
@@ -175,6 +205,7 @@ type AuthStateOptions = {
  orgRole?: OrganizationCustomRoleKey | null;
  orgSlug?: string | null;
  orgPermissions?: OrganizationCustomPermissionKey[] | null;
+ __experimental_features?: string | null;
  getToken: GetToken;
  signOut: SignOut;
  has: (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => boolean;

packages/types/src/authorization.ts

@@ -0,0 +1,34 @@
+declare global {
+ // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+ interface ClerkAuthorization {}
+}
+
+interface AuthorizationKeysBase {
+ role: string;
+ permission: string;
+ __experimental_feature: string;
+}
+
+interface AuthorizationKeysPlaceholder {
+ role: unknown;
+ permission: unknown;
+ __experimental_feature: unknown;
+}
+
+export type RoleKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['role'] extends string
+ ? ClerkAuthorization['role']
+ : AuthorizationKeysBase['role']
+ : AuthorizationKeysBase['role'];
+
+export type PermissionKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['permission'] extends string
+ ? ClerkAuthorization['permission']
+ : AuthorizationKeysBase['permission']
+ : AuthorizationKeysBase['permission'];
+
+export type FeatureKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['__experimental_feature'] extends string
+ ? ClerkAuthorization['__experimental_feature']
+ : AuthorizationKeysBase['__experimental_feature']
+ : AuthorizationKeysBase['__experimental_feature'];

packages/types/src/index.ts

@@ -3,6 +3,7 @@ export * from './appearance';
 export * from './elementIds';
 export * from './attributes';
 export * from './authConfig';
+export * from './authorization';
 export * from './backupCode';
 export * from './clerk';
 export * from './client';

packages/types/src/jwtv2.ts

@@ -119,14 +119,19 @@ type JWTPayloadBase = {
  * Any other JWT Claim Set member.
  */
  [propName: string]: unknown;
+
+ /**
+ * Feature claims, you can have multiple features in the same claim. e.g.: "impersonation,emails"
+ * @experimental
+ */
+ fea?: string | null;
 };
 
 export type VersionedJwtPayload =
  | {
  ver?: never;
 
  /**
- *
  * Active organization permissions.
  */
  org_permissions?: OrganizationCustomPermissionKey[];

packages/types/src/session.ts

@@ -1,3 +1,4 @@
+import type { FeatureKey } from './authorization';
 import type {
  BackupCodeAttempt,
  EmailCodeAttempt,
@@ -52,12 +53,19 @@ export type CheckAuthorizationParamsWithCustomPermissions = WithReverification<
  | {
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  role?: never;
  permission: OrganizationCustomPermissionKey;
+ __experimental_feature?: never;
  }
- | { role?: never; permission?: never }
+ | {
+ role?: never;
+ permission?: never;
+ __experimental_feature: FeatureKey;
+ }
+ | { role?: never; permission?: never; __experimental_feature?: never }
 >;
 
 export type CheckAuthorization = CheckAuthorizationFn<CheckAuthorizationParams>;
@@ -90,12 +98,19 @@ export type CheckAuthorizationParamsFromSessionClaims<P extends OrganizationCust
  | {
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  role?: never;
  permission: DisallowSystemPermissions<P>;
+ __experimental_feature?: never;
+ }
+ | {
+ role?: never;
+ permission?: never;
+ __experimental_feature: FeatureKey;
  }
- | { role?: never; permission?: never }
+ | { role?: never; permission?: never; __experimental_feature?: never }
 >;
 
 /**

.changeset/curvy-teeth-watch.md

@@ -0,0 +1,9 @@
+---
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/shared': patch
+'@clerk/types': patch
+---
+
+Add feature param to has

packages/backend/src/tokens/authObjects.ts

@@ -43,6 +43,7 @@ type SignedInAuthObjectProperties = {
  * [fistFactorAge, secondFactorAge]
  */
  factorVerificationAge: [firstFactorAge: number, secondFactorAge: number] | null;
+ __experimental_features?: string | null;
 };
 
 /**
@@ -114,6 +115,7 @@ const generateSignedInAuthObjectProperties = (claims: JwtPayload): SignedInAuthO
  orgSlug: claims.org_slug,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features: claims.fea,
  };
 };
 
@@ -125,8 +127,18 @@ export function signedInAuthObject(
  sessionToken: string,
  sessionClaims: JwtPayload,
 ): SignedInAuthObject {
- const { actor, sessionId, sessionStatus, userId, orgId, orgRole, orgSlug, orgPermissions, factorVerificationAge } =
- generateSignedInAuthObjectProperties(sessionClaims);
+ const {
+ actor,
+ sessionId,
+ sessionStatus,
+ userId,
+ orgId,
+ orgRole,
+ orgSlug,
+ orgPermissions,
+ factorVerificationAge,
+ __experimental_features,
+ } = generateSignedInAuthObjectProperties(sessionClaims);
  const apiClient = createBackendApiClient(authenticateContext);
  const getToken = createGetToken({
  sessionId,
@@ -145,8 +157,16 @@ export function signedInAuthObject(
  orgSlug,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features,
  getToken,
- has: createCheckAuthorization({ orgId, orgRole, orgPermissions, userId, factorVerificationAge }),
+ has: createCheckAuthorization({
+ orgId,
+ orgRole,
+ orgPermissions,
+ userId,
+ factorVerificationAge,
+ __experimental_features,
+ }),
  debug: createDebug({ ...authenticateContext, sessionToken }),
  };
 }

packages/clerk-js/src/core/resources/Session.ts

@@ -115,6 +115,8 @@ export class Session extends BaseResource implements SessionResource {
  orgId: activeMembership?.id,
  orgRole: activeMembership?.role,
  orgPermissions: activeMembership?.permissions,
+ // TODO: retrieve features
+ __experimental_features: 'testfeature',
  })(params);
  };
 

packages/react/src/components/controlComponents.tsx

@@ -1,6 +1,7 @@
 import { deprecated } from '@clerk/shared/deprecated';
 import type {
  CheckAuthorizationWithCustomPermissions,
+ FeatureKey,
  HandleOAuthCallbackParams,
  OrganizationCustomPermissionKey,
  OrganizationCustomRoleKey,
@@ -61,21 +62,31 @@ export type ProtectProps = React.PropsWithChildren<
  condition?: never;
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  condition?: never;
  role?: never;
  permission: OrganizationCustomPermissionKey;
+ __experimental_feature?: never;
  }
  | {
  condition: (has: CheckAuthorizationWithCustomPermissions) => boolean;
  role?: never;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  condition?: never;
  role?: never;
  permission?: never;
+ __experimental_feature: FeatureKey;
+ }
+ | {
+ condition?: never;
+ role?: never;
+ permission?: never;
+ __experimental_feature?: never;
  }
  ) & {
  fallback?: React.ReactNode;
@@ -89,8 +100,10 @@ export type ProtectProps = React.PropsWithChildren<
  * ```
  * <Protect permission="a_permission_key" />
  * <Protect role="a_role_key" />
+ * <Protect __experimental_feature"a_feature_key" />
  * <Protect condition={(has) => has({permission:"a_permission_key"})} />
  * <Protect condition={(has) => has({role:"a_role_key"})} />
+ * <Protect condition={(has) => has({__experimental_feature:"a_feature_key"})} />
  * <Protect fallback={<p>Unauthorized</p>} />
  * ```
  */
@@ -127,7 +140,7 @@ export const Protect = ({ children, fallback, treatPendingAsSignedOut, ...restAu
  return unauthorized;
  }
 
- if (restAuthorizedParams.role || restAuthorizedParams.permission) {
+ if (restAuthorizedParams.role || restAuthorizedParams.permission || restAuthorizedParams.__experimental_feature) {
  if (has(restAuthorizedParams)) {
  return authorized;
  }

packages/react/src/hooks/useAuth.ts

@@ -144,7 +144,17 @@ export function useDerivedAuth(
  authObject: any,
  { treatPendingAsSignedOut = true }: PendingSessionOptions = {},
 ): UseAuthReturn {
- const { userId, orgId, orgRole, has, signOut, getToken, orgPermissions, factorVerificationAge } = authObject ?? {};
+ const {
+ userId,
+ orgId,
+ orgRole,
+ has,
+ signOut,
+ getToken,
+ orgPermissions,
+ factorVerificationAge,
+ __experimental_features,
+ } = authObject ?? {};
 
  const derivedHas = useCallback(
  (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
@@ -157,9 +167,10 @@ export function useDerivedAuth(
  orgRole,
  orgPermissions,
  factorVerificationAge,
+ __experimental_features,
  })(params);
  },
- [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge],
+ [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge, __experimental_features],
  );
 
  const payload = resolveAuthState({

packages/shared/src/authorization.ts

@@ -20,13 +20,19 @@ type AuthorizationOptions = {
  orgRole: string | null | undefined;
  orgPermissions: string[] | null | undefined;
  factorVerificationAge: [number, number] | null;
+ __experimental_features?: string | null;
 };
 
 type CheckOrgAuthorization = (
  params: { role?: OrganizationCustomRoleKey; permission?: OrganizationCustomPermissionKey },
  { orgId, orgRole, orgPermissions }: AuthorizationOptions,
 ) => boolean | null;
 
+type CheckFeatureAuthorization = (
+ params: { __experimental_feature?: string },
+ { __experimental_features }: AuthorizationOptions,
+) => boolean | null;
+
 type CheckReverificationAuthorization = (
  params: {
  reverification?: ReverificationConfig;
@@ -85,6 +91,25 @@ const checkOrgAuthorization: CheckOrgAuthorization = (params, options) => {
  return null;
 };
 
+const checkFeatureAuthorization: CheckFeatureAuthorization = (param, options) => {
+ const { __experimental_feature: feature } = param;
+ const { __experimental_features } = options;
+
+ if (!feature) {
+ return null;
+ }
+
+ if (!__experimental_features) {
+ return null;
+ }
+
+ if (typeof __experimental_features === 'string') {
+ return __experimental_features.split(',').includes(feature);
+ }
+
+ return null;
+};
+
 const validateReverificationConfig = (config: ReverificationConfig | undefined | null) => {
  if (!config) {
  return false;
@@ -156,6 +181,11 @@ const createCheckAuthorization = (options: AuthorizationOptions): CheckAuthoriza
 
  const orgAuthorization = checkOrgAuthorization(params, options);
  const reverificationAuthorization = checkReverificationAuthorization(params, options);
+ const featureAuthorization = checkFeatureAuthorization(params, options);
+
+ if (featureAuthorization) {
+ return featureAuthorization;
+ }
 
  if ([orgAuthorization, reverificationAuthorization].some(a => a === null)) {
  return [orgAuthorization, reverificationAuthorization].some(a => a === true);
@@ -175,6 +205,7 @@ type AuthStateOptions = {
  orgRole?: OrganizationCustomRoleKey | null;
  orgSlug?: string | null;
  orgPermissions?: OrganizationCustomPermissionKey[] | null;
+ __experimental_features?: string | null;
  getToken: GetToken;
  signOut: SignOut;
  has: (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => boolean;

packages/types/src/authorization.ts

@@ -0,0 +1,34 @@
+declare global {
+ // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+ interface ClerkAuthorization {}
+}
+
+interface AuthorizationKeysBase {
+ role: string;
+ permission: string;
+ __experimental_feature: string;
+}
+
+interface AuthorizationKeysPlaceholder {
+ role: unknown;
+ permission: unknown;
+ __experimental_feature: unknown;
+}
+
+export type RoleKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['role'] extends string
+ ? ClerkAuthorization['role']
+ : AuthorizationKeysBase['role']
+ : AuthorizationKeysBase['role'];
+
+export type PermissionKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['permission'] extends string
+ ? ClerkAuthorization['permission']
+ : AuthorizationKeysBase['permission']
+ : AuthorizationKeysBase['permission'];
+
+export type FeatureKey = ClerkAuthorization extends AuthorizationKeysPlaceholder
+ ? ClerkAuthorization['__experimental_feature'] extends string
+ ? ClerkAuthorization['__experimental_feature']
+ : AuthorizationKeysBase['__experimental_feature']
+ : AuthorizationKeysBase['__experimental_feature'];

packages/types/src/index.ts

@@ -3,6 +3,7 @@ export * from './appearance';
 export * from './elementIds';
 export * from './attributes';
 export * from './authConfig';
+export * from './authorization';
 export * from './backupCode';
 export * from './clerk';
 export * from './client';

packages/types/src/jwtv2.ts

@@ -119,14 +119,19 @@ type JWTPayloadBase = {
  * Any other JWT Claim Set member.
  */
  [propName: string]: unknown;
+
+ /**
+ * Feature claims, you can have multiple features in the same claim. e.g.: "impersonation,emails"
+ * @experimental
+ */
+ fea?: string | null;
 };
 
 export type VersionedJwtPayload =
  | {
  ver?: never;
 
  /**
- *
  * Active organization permissions.
  */
  org_permissions?: OrganizationCustomPermissionKey[];

packages/types/src/session.ts

@@ -1,3 +1,4 @@
+import type { FeatureKey } from './authorization';
 import type {
  BackupCodeAttempt,
  EmailCodeAttempt,
@@ -52,12 +53,19 @@ export type CheckAuthorizationParamsWithCustomPermissions = WithReverification<
  | {
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  role?: never;
  permission: OrganizationCustomPermissionKey;
+ __experimental_feature?: never;
  }
- | { role?: never; permission?: never }
+ | {
+ role?: never;
+ permission?: never;
+ __experimental_feature: FeatureKey;
+ }
+ | { role?: never; permission?: never; __experimental_feature?: never }
 >;
 
 export type CheckAuthorization = CheckAuthorizationFn<CheckAuthorizationParams>;
@@ -90,12 +98,19 @@ export type CheckAuthorizationParamsFromSessionClaims<P extends OrganizationCust
  | {
  role: OrganizationCustomRoleKey;
  permission?: never;
+ __experimental_feature?: never;
  }
  | {
  role?: never;
  permission: DisallowSystemPermissions<P>;
+ __experimental_feature?: never;
+ }
+ | {
+ role?: never;
+ permission?: never;
+ __experimental_feature: FeatureKey;
  }
- | { role?: never; permission?: never }
+ | { role?: never; permission?: never; __experimental_feature?: never }
 >;
 
 /**