@tsndr/cloudflare-worker-jwt/index.d.ts

A lightweight JWT implementation with ZERO dependencies for Cloudflare Worker

/**
 * @typedef JwtAlgorithm
 * @type {"none" | "ES256" | "ES384" | "ES512" | "HS256" | "HS384" | "HS512" | "RS256" | "RS384" | "RS512"}
 */
export type JwtAlgorithm = "none" | "ES256" | "ES384" | "ES512" | "HS256" | "HS384" | "HS512" | "RS256" | "RS384" | "RS512";
/**
 * @typedef JwtAlgorithms
 */
export type JwtAlgorithms = {
    [key: string]: SubtleCryptoImportKeyAlgorithm;
};
/**
 * @typedef JwtHeader
 * @prop {string} [typ] Type
 */
export type JwtHeader<T = {}> = {
    /**
     * Type (default: `"JWT"`)
     *
     * @default "JWT"
     */
    typ?: string;
    /**
     * Algorithm (default: `"HS256"`)
     *
     * @default "HS256"
     */
    alg?: JwtAlgorithm;
} & T;
/**
 * @typedef JwtPayload
 * @prop {string} [iss] Issuer
 * @prop {string} [sub] Subject
 * @prop {string | string[]} [aud] Audience
 * @prop {string} [exp] Expiration Time
 * @prop {string} [nbf] Not Before
 * @prop {string} [iat] Issued At
 * @prop {string} [jti] JWT ID
 */
export type JwtPayload<T = {
    [key: string]: any;
}> = {
    /** Issuer */
    iss?: string;
    /** Subject */
    sub?: string;
    /** Audience */
    aud?: string | string[];
    /** Expiration Time */
    exp?: number;
    /** Not Before */
    nbf?: number;
    /** Issued At */
    iat?: number;
    /** JWT ID */
    jti?: string;
} & T;
/**
 * @typedef JwtOptions
 * @prop {JwtAlgorithm | string} algorithm
 */
export type JwtOptions = {
    algorithm?: JwtAlgorithm | string;
};
/**
 * @typedef JwtSignOptions
 * @extends JwtOptions
 * @prop {JwtHeader} [header]
 */
export type JwtSignOptions<T> = {
    header?: JwtHeader<T>;
} & JwtOptions;
/**
 * @typedef JwtVerifyOptions
 * @extends JwtOptions
 * @prop {boolean} [throwError=false] If `true` throw error if checks fail. (default: `false`)
 */
export type JwtVerifyOptions = {
    /**
    * Clock tolerance to help with slightly out of sync systems
    */
    clockTolerance?: number;
    /**
     * If `true` throw error if checks fail. (default: `false`)
     *
     * @default false
    */
    throwError?: boolean;
} & JwtOptions;
/**
 * @typedef JwtData
 * @prop {JwtHeader} header
 * @prop {JwtPayload} payload
 */
export type JwtData<Payload = {}, Header = {}> = {
    header: JwtHeader<Header>;
    payload: JwtPayload<Payload>;
};
/**
 * Signs a payload and returns the token
 *
 * @param payload The payload object. To use `nbf` (Not Before) and/or `exp` (Expiration Time) add `nbf` and/or `exp` to the payload.
 * @param secret A string which is used to sign the payload.
 * @param [options={ algorithm: "HS256", header: { typ: "JWT" } }] The options object or the algorithm.
 * @throws If there"s a validation issue.
 * @returns Returns token as a `string`.
 */
export declare function sign<Payload = {}, Header = {}>(payload: JwtPayload<Payload>, secret: string | JsonWebKeyWithKid | CryptoKey | undefined, options?: JwtSignOptions<Header> | JwtAlgorithm): Promise<string>;
/**
 * Verifies the integrity of the token and returns a boolean value.
 *
 * @param token The token string generated by `sign()`.
 * @param secret The string which was used to sign the payload.
 * @param options The options object or the algorithm.
 * @throws Throws integration errors and if `options.throwError` is set to `true` also throws `NOT_YET_VALID`, `EXPIRED` or `INVALID_SIGNATURE`.
 * @returns Returns the decoded token or `undefined`.
 */
export declare function verify<Payload = {}, Header = {}>(token: string, secret: string | JsonWebKeyWithKid | CryptoKey | undefined, options?: JwtVerifyOptions | JwtAlgorithm): Promise<JwtData<Payload, Header> | undefined>;
/**
 * Returns the payload **without** verifying the integrity of the token. Please use `verify()` first to keep your application secure!
 *
 * @param token The token string generated by `sign()`.
 * @returns Returns an `object` containing `header` and `payload`.
 */
export declare function decode<Payload = {}, Header = {}>(token: string): JwtData<Payload, Header>;
declare const _default: {
    sign: typeof sign;
    verify: typeof verify;
    decode: typeof decode;
};
export default _default;