add reserved claims types

[dschaller]

By submitting a PR to this repository, you agree to the terms within the Auth0 Code of Conduct. Please see the contributing guidelines for how to create and submit a high-quality PR for this repo.

Description

Describe the purpose of this PR along with any background information and the impacts of the proposed change. For the benefit of the community, please do not assume prior context.

Provide details that support your chosen implementation, including: breaking changes, alternatives considered, changes to the API, etc.

If the UI is being changed, please provide screenshots.

Add type definitions for reserved claims as listed in section 4.1 of the RFC.

Checklist

• All active GitHub checks for tests, formatting, and security are passing
• The correct base branch is being used, if not master

[Sambego]

We're having a bit of a discussion about whether to return unkown, or provide the opportunity to use a generic to cast the returned type in the comments of #105.

I would like to keep these types as flexible as possible. Would the generic approach where you can do the following also work for you?

type JwtPayload = {
  iat: number;
  exp: number;
  ...
  roles: string[];
};

const { username } = jwt_decode<JwtPayload>(token);

[dschaller]

@Sambego that would work but I'd be curious why use unknown if the RFC defines reserved optional claims? Users could then extend the type interface if they have custom claims that they want to add.

[felixmosh]

You can combine both approaches, generics with default value.

export interface JwtClaims {
  iss?: string;
  sub?: string;
  aud?: string[] | string;
  exp?: number;
  nbf?: number;
  iat?: number;
  jti?: string;
}

export default function jwtDecode<T = JwtClaims>(token: string, options?: JwtDecodeOptions): T;
// or using extention
export default function jwtDecode<T extends JwtClaims = JwtClaims>(token: string, options?: JwtDecodeOptions): T;

This way, you can pass from the outside your type but by default it will be JwsClaims.

Example with the last (with extends) type

[Sambego]

Thanks, everybody for chiming in on this, your insights are appreciated 💪

• Went with the suggestion by @vazgabriel as it would not introduce a breaking change
• Export a default type for a JWT header and payload, which can be used as-is, or extended, and passed to the generic.

[Sambego]

These updates are available in v3.1.2