@clerk/backend-core

Deprecation warning

This package has been deprecated in favor of the isomorphic @clerk/backend which is now used across all server-enabled Clerk packages. This package will not receive any future updates. It should not be used directly - please use as a reference only.

Overview

This package provides Clerk Backend API core resources and low-level authentication utilities for JavaScript environments. It is mostly used as the base for other Clerk SDKs.

Getting Started

Installation

npm install @clerk/backend-core

Build

To build the package locally with the TypeScript compiler, run:

npm run build

Architecture

@clerk/backend-core contains all the logic for basic Clerk functionalities, without being platform/environment, specific such as:

• Determining the authentication state of a session.
• Validating a Clerk token state.
• Clerk API resource management.

How it works

This package is used as the base building block for Clerk JavaScript SDKs and environments. This is achieved by providing all the required business logic if only a few environment-specific utilities are implemented by the client.

In essence, the client should supply these key functions in the Clerk Base and ClerkBackendApi classes:

1. Public key import importKeyFunction.
2. JWT signature verification verifySignatureFunction.
3. Base64 decoding decodeBase64Function.
4. HTTP fetching utility for the API resource management ClerkFetcher.

After supplying those in the Base and ClerkBackendApi classes, you can use all the Clerk utilities required for the SDK business logic.

Usage

Creating a Base for a new SDK

const importKey = async (jwk: JsonWebKey, algorithm: Algorithm) => {
  //  ...
};

const verifySignature = async (algorithm: Algorithm, key: CryptoKey, signature: Uint8Array, data: Uint8Array) => {
  // ...
};

const decodeBase64 = (base64: string) => {
  // ...
};

/** Base initialization */
const examplePlatformBase = new Base(importKey, verifySignature, decodeBase64);

After creating the Base instance you can use core functions such as:

examplePlatformBase.verifySessionToken(...);

examplePlatformBase.getAuthState(...);

The Base utilities include the building blocks for developing any extra logic and middleware required for the target platform.

Validate the Authorized Party of a session token

Clerk's JWT session token, contains the azp claim, which equals the Origin of the request during token generation. You can provide a list of whitelisted origins to verify against, during every token verification, to protect your application of the subdomain cookie leaking attack. You can find an example below:

const authorizedParties = ['http://localhost:3000', 'https://example.com'];

examplePlatformBase.verifySessionToken(token > { authorizedParties });

Clerk API Resources

API resource management is also provided by this package through the ClerkBackendApi class. For more information on the API resources you can checkout the resource documentation page.

To use the Clerk Backend API wrapper in any JavaScript platform, you would need to provide some specific SDK information and an HTTP fetching utility. See more at the ClerkBackendAPIProps implementation.

Support

You can get in touch with us in any of the following ways:

• Join our official community Discord server
• Open a GitHub support issue
• Contact options listed on our Support page

Contributing

We're open to all community contributions! If you'd like to contribute in any way, please read our contribution guidelines.

Security

@clerk/backend-core follows good practices of security, but 100% security cannot be assured.

@clerk/backend-core is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

License

This project is licensed under the MIT license.

See LICENSE for more information.